Introduction

Purpose

This is functional specification for Integrating CS alerts via SNMP to external management system feature of Cloudstack.

References

https://issues.apache.org/jira/browse/CLOUDSTACK-680

Glossary

  • SNMP - Simple Network Management Protocol
  • OID     - Object Identifier
  • IANA   - Internet Assigned Numbers Authority
  • MIB     - Management Information Base
  • ASN.1 - Abstract Syntax Notation One
  • PDU    - Protocol Data Unit

Brief Introduction to SNMP

Some Information about MIB

Use cases

These SNMP alerts can be used by SNMP managers (external running entities which can receive SNMP alerts) to find out the problems in Cloudstack and can act accordingly. This is similar to alerts that we see on dashboard of Cloudstack.

  1. Admin will set the name, IP , Ports, community  of SNMP managers through Cloudstack configuration file, log4j-cloud.xml and those managers will be able to get SNMP alerts then.
  2. Admin can  delete the SNMP Managers by removing them from configuration file

Feature Specifications

In this feature we are implementing partial SNMP Agent for Cloudstack. Partial SNMP Agent means we are just sending SNMP traps for alerts  and not processing  requests from SNMP Managers. In the current scenario we are writing alerts to database and are shown on Cloudstack dashboard. Now in addition to that we are sending an alert for SNMP managers  also. For that purpose we will be defining MIB files. MIB files are written in ASN.1 language and contains the mapping of OID and variable mappings. MIB file acts like DNS server to identify the variable corresponding to OID.

SNMP version 2 will be supported with this feature. 

There are two ways of getting OIDs for variable

  • dynamically generate OID from MIB files, requires java code generation
  • hardcode OIDs in code

Currently  hardcoding  OIDs in code of cloudstack since those are defined by us and code generation will require some processing. We have created MIB file for users.

 The root OID for Apache CloudStack is 1.3.6.1.4.1.18060.15 .. we define the following traps

  1. availableMemory : Available Memory below configured threshold
  2. availableCpu :  Unallocated CPU below configured threshold
  3. availableStorage :  Available Storage below configured threshold
  4. remainingStorageAllocated : Remaining unallocated Storage is below configured threshold
  5. unallocatedVirtualNetworkpublicIp : Number of unallocated virtual network public IPs is below configured threshold
  6. unallocatedPrivateIp : Number of unallocated private IPs is below configured threshold
  7. availableSecondaryStorage :  Available Secondary Storage in availability zone is below configured threshold
  8. host : host related alerts like host disconnected etc
  9. userVmState : User VM stopped unexpectedly
  10. domainRouterVmState : Domain Router VM stopped unexpectedly
  11. consoleProxyVmState : Console Proxy VM stopped unexpectedly
  12. routingConnection : lost connection to default route (to the gateway)
  13. storageIssueSystemVms : storage issue in system VMs
  14. usageServerStatus : No usage server process running
  15. managmentNode : Management network CIDR is not configured originally
  16. domainRouterMigrate : Domain Router VM Migration was unsuccessful
  17. consoleProxyMigrate : Console Proxy VM Migration was unsuccessful
  18. userVmMigrate  : User  VM Migration was unsuccessful
  19. unallocatedVlan : Number of unallocated VLANs is below configured threshold in availability zone
  20. ssvmStopped : SSVM stopped unexpectedly
  21. usageServerResult :  Usage job failed
  22. storageDelete : Failed to Delete storage pool
  23. updateResourceCount : Failed to update the resource count
  24. usageSanityResult : Usage Sanity Check failed
  25. unallocatedDirectAttachedPublicIp : Number of unallocated shared network IPs is low in availability zone
  26. unallocatedLocalStorage : Remaining unallocated Local Storage is below configured threshold
  27. resourceLimitExceeded : Resource limit exceeds the limit

Each trap contains following information

  1. message
  2. podId
  3. dataCenterId
  4. clusterId
  5. generationTime

currently sending  all the alerts to administrator and he will filter alerts according to his needs.

For this feature, we will be using  snmp4j library with Apache License

Architecture and Design description

This feature will be implemented as plugin. This feature will use the log4j Appender to get the required alerts and will generate the SNMP trap from that. To do so following classes will be used.

Classes

We will add following classes

  • SnmpHelper  contains mainly three methods
    • createPDU(SnmpTrapInfo) :  creates the SNMP Trap PDU
    • sendSnmpTrap(SnmpTrapInfo) : sends the SNMP Trap
  • SnmpConstants2  :  contains the required constants
  • SnmpEnhancedPatternLayout : parses the alert event
  • SnmpTrapInfo : conatins the parsed info, which will be sent as SNMP Trap
  • SnmpTrapAppender contains mainly two methods
    • append(LoggingEvent) : sends the trap to configured SNMP Managers using SnmpHelper class
    • setSnmpHelpers() : sets the Snmp Managers to whom traps will be sent

Changes in log4j-cloud.xml

To configure multiple SNMP Managers one needs to add following appender in log4j-cloud.xml
   <appender name="SNMP" class="org.apache.cloudstack.alert.snmp.SnmpTrapAppender">
      <param name="Threshold" value="WARN"/>
      <param name="SnmpManagerIpAddresses" value=""/>
      <param name="SnmpManagerPorts" value=""/>
      <param name="SnmpManagerCommunities" value=""/>
      <layout class="org.apache.cloudstack.alert.snmp.SnmpEnhancedPatternLayout">
         <param name="PairDelimeter" value="//"/>
         <param name="KeyValueDelimeter" value="::"/>
      </layout>
   </appender>

To specify multiple  SnmpManagerIpAddresses one has to modify as follows with each SNMP Manager separated by ,

   <appender name="SNMP" class="org.apache.cloudstack.alert.snmp.SnmpTrapAppender">
      <param name="Threshold" value="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">
         <param name="PairDelimeter" value="//"/>
         <param name="KeyValueDelimeter" value="::"/>
      </layout>
   </appender>

Following loggers will also be added      

   <logger name="org.apache.cloudstack.alerts" additivity="false">
      <level value="WARN"/>
      <appender-ref ref="SYSLOG"/>
      <appender-ref ref="CONSOLE"/>
      <appender-ref ref="FILE"/>
      <appender-ref ref="SNMP"/>
   </logger>
 

MIB file for CloudStack Alerts

MIB file for CloudStack Alerts (for CloudStack version 4.3 and above)

  • No labels