You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cloudstack.apache.org by jt...@apache.org on 2013/08/21 01:01:11 UTC
git commit: updated refs/heads/master to 72299f4
Updated Branches:
refs/heads/master e65a302f1 -> 72299f49f
CLOUDSTACK-680. DOC. Add section about sending alerts to external SNMP managers/Syslog managers.
Project: http://git-wip-us.apache.org/repos/asf/cloudstack/repo
Commit: http://git-wip-us.apache.org/repos/asf/cloudstack/commit/72299f49
Tree: http://git-wip-us.apache.org/repos/asf/cloudstack/tree/72299f49
Diff: http://git-wip-us.apache.org/repos/asf/cloudstack/diff/72299f49
Branch: refs/heads/master
Commit: 72299f49fd3596b53c7fc7de42491f081940aef9
Parents: e65a302
Author: Jessica <je...@citrix.com>
Authored: Tue Aug 20 16:00:09 2013 -0700
Committer: Jessica <je...@citrix.com>
Committed: Tue Aug 20 16:00:22 2013 -0700
----------------------------------------------------------------------
docs/en-US/admin-alerts.xml | 95 +++++++++++++++++++++++++++++++++++++++-
1 file changed, 94 insertions(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cloudstack/blob/72299f49/docs/en-US/admin-alerts.xml
----------------------------------------------------------------------
diff --git a/docs/en-US/admin-alerts.xml b/docs/en-US/admin-alerts.xml
index 5354c5e..e98f79d 100644
--- a/docs/en-US/admin-alerts.xml
+++ b/docs/en-US/admin-alerts.xml
@@ -31,5 +31,98 @@
<listitem><para>The Management Server cluster runs low on CPU, memory, or storage resources</para></listitem>
<listitem><para>The Management Server loses heartbeat from a Host for more than 3 minutes</para></listitem>
<listitem><para>The Host cluster runs low on CPU, memory, or storage resources</para></listitem>
- </itemizedlist>
+ </itemizedlist>
+ <section id="external-snmp-manager">
+ <!-- CLOUDSTACK-680 -->
+ <title>Sending Alerts to External SNMP and Syslog Managers</title>
+ <para>In addition to showing administrator alerts on the Dashboard in the &PRODUCT; UI and
+ sending them in email, &PRODUCT; can also send the same alerts to external SNMP or
+ Syslog management software. This is useful if you prefer to use an SNMP or Syslog
+ manager to monitor your cloud.</para>
+ <para>The alerts which can be sent are listed in <xref linkend="alerts"/>. You can also
+ display the most up to date list by calling the API command listAlerts.</para>
+ <section id="snmp-alert-details">
+ <title>SNMP Alert Details</title>
+ <para>The supported protocol is SNMP version 2.</para>
+ <para>Each SNMP trap contains the following information: message, podId, dataCenterId, clusterId, and generationTime.</para>
+ </section>
+ <section id="syslog-alert-details">
+ <title>Syslog Alert Details</title>
+ <para>&PRODUCT; generates a syslog message for every alert. Each syslog message incudes
+ the fields alertType, message, podId, dataCenterId, and clusterId, in the following
+ format. If any field does not have a valid value, it will not be included.</para>
+ <programlisting>Date severity_level Management_Server_IP_Address/Name alertType:: value dataCenterId:: value podId:: value clusterId:: value message:: value</programlisting>
+ <para>For example:</para>
+ <programlisting>Mar 4 10:13:47 WARN localhost alertType:: managementNode message:: Management server node 127.0.0.1 is up</programlisting>
+ </section>
+ <section id="snmp-syslog-config">
+ <title>Configuring SNMP and Syslog Managers</title>
+ <para>To configure one or more SNMP managers or Syslog managers to receive alerts from
+ &PRODUCT;:</para>
+ <orderedlist>
+ <listitem><para>For an SNMP manager, install the &PRODUCT; MIB file on your SNMP manager system.
+ This maps the SNMP OIDs to trap types that can be more easily read by users.
+ The file must be publicly available.
+ For more information on how to install this file, consult the documentation provided with the SNMP manager.</para></listitem>
+ <listitem>
+ <para>Edit the file /etc/cloudstack/management/log4j-cloud.xml.</para>
+ <programlisting># vi /etc/cloudstack/management/log4j-cloud.xml</programlisting>
+ </listitem>
+ <listitem>
+ <para>Add an entry using the syntax shown below. Follow the appropriate example
+ depending on whether you are adding an SNMP manager or a Syslog manager. To specify
+ multiple external managers, separate the IP addresses and other configuration values
+ with commas (,).</para>
+ <note>
+ <para>The recommended maximum number of SNMP or Syslog managers is 20 for
+ each.</para>
+ </note>
+ <para/>
+ <para>The following example shows how to configure two SNMP managers at IP addresses
+ 10.1.1.1 and 10.1.1.2. Substitute your own IP addresses, ports, and communities. Do
+ not change the other values (name, threshold, class, and layout values).</para>
+ <programlisting><appender name="SNMP" class="org.apache.cloudstack.alert.snmp.SnmpTrapAppender">
+ <param name="Threshold" value="WARN"/> <!-- Do not edit. The alert feature assumes WARN. -->
+ <param name="SnmpManagerIpAddresses" value="10.1.1.1,10.1.1.2"/>
+ <param name="SnmpManagerPorts" value="162,162"/>
+ <param name="SnmpManagerCommunities" value="public,public"/>
+ <layout class="org.apache.cloudstack.alert.snmp.SnmpEnhancedPatternLayout"> <!-- Do not edit -->
+ <param name="PairDelimeter" value="//"/>
+ <param name="KeyValueDelimeter" value="::"/>
+ </layout>
+</appender></programlisting>
+ <para>The following example shows how to configure two Syslog managers at IP
+ addresses 10.1.1.1 and 10.1.1.2. Substitute your own IP addresses. You can
+ set Facility to any syslog-defined value, such as LOCAL0 - LOCAL7. Do not
+ change the other values.</para>
+ <programlisting><appender name="ALERTSYSLOG">
+ <param name="Threshold" value="WARN"/>
+ <param name="SyslogHosts" value="10.1.1.1,10.1.1.2"/>
+ <param name="Facility" value="LOCAL6"/>
+ <layout>
+ <param name="ConversionPattern" value=""/>
+ </layout>
+</appender></programlisting>
+ </listitem>
+ <listitem>
+ <para>If your cloud has multiple Management Server nodes, repeat these steps to edit
+ log4j-cloud.xml on every instance.</para>
+ </listitem>
+ <listitem>
+ <para>If you have made these changes while the Management Server is running, wait a
+ few minutes for the change to take effect.</para>
+ </listitem>
+ </orderedlist>
+ <para><emphasis role="bold">Troubleshooting:</emphasis> If no alerts appear at the
+ configured SNMP or Syslog manager after a reasonable amount of time, it is likely that
+ there is an error in the syntax of the <appender> entry in log4j-cloud.xml. Check
+ to be sure that the format and settings are correct.</para>
+ </section>
+ <section id="delete-snmp-syslog-manager">
+ <title>Deleting an SNMP or Syslog Manager</title>
+ <para>To remove an external SNMP manager or Syslog manager so that it no longer receives
+ alerts from &PRODUCT;, remove the corresponding entry from the file
+ /etc/cloudstack/management/log4j-cloud.xml.</para>
+ </section>
+ </section>
</section>