sensu-plugins-snmptrap-extension 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b9ade74acbf2e688353c1fbe51c10fb310d33993
-  data.tar.gz: 183bbd5e5cdb31f9a0af9ed1a1f22344da3b5eeb
+  metadata.gz: b9a0ba4669fb05ae1039fbf59f4bb0a282f593ab
+  data.tar.gz: 36686e2a0d14e5e979a9896e6be199cf12ddd507
 SHA512:
-  metadata.gz: 1bd4fb7ba9941e00a1deadcd5d6b10232824a87b7156b684702a85aaffc55471ca0fb34be1cb1bc038587b0d3b6959b28db88232f253af6c564897f719b7b47f
-  data.tar.gz: 686ece3016f49c2e329ee4988f84b2831d1cbccf1c06452cff74ab96197ac8acf7e2e692767494c3940ddbecc39f1da9b306bb71782c4eb79e3b24d011fd29ae
+  metadata.gz: 9b73adb6c909802ba22b8371de7a5fa019d8073f709604881e2498a67c7a6ce97a6d5f7463e49380290de05fc99d69877732c3a1148588a23197baebca6079b8
+  data.tar.gz: 0deabed059f0438d22a63f33207fb72f1c986273420755a93547f3388ba874fb56318c4f63842a3cf728932762a741d5a382b7481df4dd4592bbceb24f3ab3c5

data/CHANGELOG.md

@@ -3,16 +3,28 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 This CHANGELOG follows the format listed at [Keep A Changelog](http://keepachangelog.com/)
 
-## Unreleased
+
+## [Unreleased]
+### Added
+
+### Changed
+
+## [0.2.0] - 2016-06-04
 ### Added
-- Rake, gemspecs and basic core test code
-- This CHANGELOG
-- Travis configuration for test building
+- README: Instructions on installation
+
+### Fixed
+- Log message handling from @amdprophet
+- Autodiscovery of sensu-client's JIT event socket
+- Better handling when the event socket is missing/unconfigured
+
 
 ### Changed
-- Moved script to bin sub-directory as part of refactor to adhere to sensu-plugin conventions
+- README: Reformatting and extended examples
+- Reduced the log noise by reducing the log severity on a number of messages
+
 
 
-## 0.0.1 - 2015-05-20
+## [0.1.0] - 2016-06-04
 ### Added
 - initial release

data/README.md

@@ -4,93 +4,193 @@ Creates an SNMP trap listening to all incoming traps on the configured interface
 
 [![Build Status](https://travis-ci.org/warmfusion/sensu-extension-snmptrap.svg)](https://travis-ci.org/warmfusion/sensu-extension-snmptrap)
 
-## TODO
+[![Gem Version](https://badge.fury.io/rb/sensu-plugins-snmptrap-extension.svg)](https://badge.fury.io/rb/sensu-plugins-snmptrap-extension)
 
-Also able to run as a 'polling' service in either Check or Metrics mode where values can be directly compared against expectations (eg value > 10)
-or where values are sent to Sensu as metrics values for charting or other purposes.
 
+# Installation
 
-## Configuration
+As sensu extensions cannot be dynamically loaded by sensu at runtime, you must
+install the extension manually once the gem has installed.
 
-The SNMPTrap configuration is defined in a json file inside conf.d/extensions (or anywhere sensu consumes configuration)
-and includes a traps configuration element that describes:
+If you're using the EMBEDDED_RUBY from sensu;
 
-* An array of traps that the extension will monitor for events (from any host) which includes
-    * `trap_oid` - the identity of the trap
-    * `trap` - A hash of key/value pairs that can be used as template values in the event
-    * `event` - The template event to send to Sensu, including {template} variables for customisation based on the message
+```
+sensu-install -p sensu-plugins-snmptrap-extension
 
+ln -s /opt/sensu/embedded/lib/ruby/gems/*/gems/sensu-plugins-snmptrap-extension-*/bin/extension-snmptrap.rb /etc/sensu/extensions/extension-snmptrap.rb
+```
 
-### Templating
+If using standalone ruby;
 
-Any value defined in `trap` that contains an OID that is included in the incoming trap can be used as part of any element of the
-event being sent to Sensu. This includes handlers, names (Only AlphaNumeric allow), status etc etc.
+```
+gem install sensu-plugins-snmptrap-extension
 
-Simply wrap your template in braces and it will be automatically replaced during processing. See the heartbeatrate in the example
-below.
+ln -s $(gem environment gemdir)/gems/sensu-plugins-snmptrap-extension*/bin/extension-snmptrap.rb /etc/sensu/extensions/extension-snmptrap.rb
+```
 
-> Note: The 'source' and 'hostname' variables are automatically provided to you. Hostname contains the FQDN name of the server (or the IP if it 
-> can't get resolved) and 'source' contains the IP address (with no lookups)
+## Configuration
 
-### Basic Extension Configuration
+The SNMPTrap configuration is defined in a json file inside conf.d/extensions (or anywhere sensu consumes configuration)
+and includes a traps configuration element that describes:
 
+* An array of traps that the extension will monitor for events (from any host) which includes
+    * `trap_oid` - the identity of the trap
+    * `trap` - A hash of key/value pairs that can be used as template values in the event
+    * `event` - The template event to send to Sensu, including {template} variables for customisation based on the message
 
-     {
-      "snmp": {
- 
-       }
-     }
 
 ### Trap Configuration
 
-Each SNMP Trap is configured in its own configuration file. This lets you easily create configuration through Puppet/Chef etc without
-having to manipulate the same configuration file.
-
-Simply create a uniquely named json file in `/etc/sensu/traps.d` containing the definition of the trap(s) you wish to capture and
-act upon.
+Each SNMP Trap is configured in its own configuration file. This lets you easily create configuration through Puppet/Chef etc without having to manipulate the same configuration file.
 
+Simply create a uniquely named json file in `/etc/sensu/traps.d` containing the definition of the trap(s) you wish to capture and act upon.
 
+```
     [
       {
         "trap_oid": "1.3.6.1.4.1.8072.2.3.0.1",
         "trap": {
-          "heartbeatrate": "1.3.6.1.4.1.8072.2.3.2.1" 
+          "heartbeatrate": "1.3.6.1.4.1.8072.2.3.2.1"
         },
         "event": {
           "name": "snmp-trap-{hostname}",
           "status": 1,
-          "output": "Heartbeat Rate {heartbeatrate}", 
-          "handler": "default"
+          "output": "Heartbeat Rate {heartbeatrate}",
+          "handler": "default",
+          "client": "{hostname}"
          }
        },
        ...
      ]
+```
 
 The JSON file is an array of trap definitions containing:
 
 * trap_oid
   * Definition: (String) The OID to monitor for events on
 * trap
-  * Definition: (Array) Key/Value pairs representing named variables (key) against the OID values of the message elements (value)
-    which can then be used as template values in the event section
+  * Definition: (Array) Key/Value pairs representing named variables (key)
+  against the OID values of the message elements (value) which can then be
+  used as template values in the event section
 * event
-  * Definition: (Hash) The event to trigger if the SNMP trap is recieved - Accepts any value that will then get sent to sensu
-    as a normal check event - this includes handlers, subdues, or custom key/value pairs as you require.
+  * Definition: (Hash) The event to trigger if the SNMP trap is received - Accepts any
+  value that will then get sent to sensu as a normal check event - this includes
+  handlers, subdues, or custom key/value pairs as you require.
   * name
-    * Definition: (String) The name of the sensu check that is sent to the sensu-client - ALPHANUMERIC and should be fairly unique (Required)
+    * Definition: (String) The name of the sensu check that is sent to the
+    sensu-client - ALPHANUMERIC and should be fairly unique (Required)
   * status
-    * Definition: (Numeric) The numeric status of the status (0-OK, 1-Warning, 2-Critical, 3-Unknown) (Required)
+    * Definition: (Numeric) The numeric status of the status
+    (0-OK, 1-Warning, 2-Critical, 3-Unknown) (Required)
   * output
     * Definition: (String) The message to send to the sensu client (Required)
   * handler
     * Definition: (String) The handler that the sensu-server should use to process this event (Optional)
 
+#### Templating
+
+Any value defined in `trap` that contains an OID that is included in the incoming trap can be used as part of any element of the
+event being sent to Sensu. This includes handlers, names (Only AlphaNumeric allow), status etc etc.
+
+Simply wrap your template in braces and it will be automatically replaced during processing. See the heartbeatrate in the example
+below.
+
+> Note: The 'source' and 'hostname' variables are automatically provided to you. Hostname contains the FQDN name of the server (or the IP if it
+> can't get resolved) and 'source' contains the IP address (with no lookups)
+
+### Override SNMP default configuration
+
+The SNMPTrap extension provides some simple configuration options which are shown
+below;
+
+     {
+      "snmp": {
+          bind: '0.0.0.0',
+          port: 1062,
+          community: 'public',
+          handler: 'default',
+          send_interval: 60,
+          trapdefs_dir: '/etc/sensu/traps.d',
+          mibs_dir: '/etc/sensu/mibs',
+          client_socket_bind: settings[:client][:socket][:bind],
+          client_socket_port: settings[:client][:socket][:port]
+       }
+     }
+
+|param|type|default|description|
+|----|----|----|---|
+|:bind|:string|0.0.0.0| IP to bind the SNMPTrap listener to |
+|:port|:integer|1062| Port to bind the SNMPTrap listener to |
+|:community|:string|"public"| *NOT USED* |
+|:handler|:string|"default"| *NOT USED* |
+|:send_interval|:integer|60| *NOT USED* |
+|:trapdefs_dir|:string|"/etc/sensu/traps.d"| Path to directory containing trap.json files to watch for |
+|:mibs_dir|:string|"/etc/sensu/mibs"| *NOT USED* - Loading MIBs causes the extension to lock up |
+|:client_socket_bind|:string| `settings[:client][:socket][:bind]` | IP to send events to when handled |
+|:client_socket_port|:integer| `settings[:client][:socket][:port]` | Port to send events to when handled|
+
+#### client_socket_xxx
+
+SNMPTrap has to use the sensu client socket to emit events when traps arrive.
+This is because there does not appear to be an asynchronous mechanism to send
+event objects into sensu-client directly, so instead a brief TCP connection
+to the sensu-client is made.
 
-## Appendix 
+The extension tries to get the configuration from the sensu config.json, so
+this should not require changing, but if you'd like to send events to another
+sensu-client you can do so here.
 
-Handy Test script:
 
+## Appendix
+
+### snmp-mibs-downloader - My SNMP doesn't work
+
+If youre using a Debian/Ubuntu based distro, you may find it hard to get SNMP working
+as it doens't include the set of MIB definitions required for alot of common systems.
+
+This is because those definitions have been copyrighted by various organisations and
+as such can only be obtained on the 'non-free' channels.
+
+To help get setup without having to install the non-free distribution, you can use
+the following few commands to get updated (and therefore working) MIB lists
+
+
+```
+apt-get install smistrip snmp
+wget http://ftp.uk.debian.org/debian/pool/non-free/s/snmp-mibs-downloader/snmp-mibs-downloader_1.1_all.deb
+dpkg -i snmp-mibs-downloader_1.1_all.deb
+```
+
+
+### Testing your configuration
+
+Add a configuration file like this into `/etc/sensu/traps.d/example_heartbeat.json`
+
+```
+[
+  {
+    "trap_oid": "1.3.6.1.4.1.8072.2.3.0.1",
+    "trap": {
+      "heartbeatrate": "1.3.6.1.4.1.8072.2.3.2.1"
+    },
+    "event": {
+      "name": "snmp-trap-{hostname}",
+      "status": 1,
+      "output": "Heartbeat Rate {heartbeatrate}",
+      "handler": "default"
+     }
+   }
+ ]
+```
+
+And then run the following command;
+
+```
     snmptrap -v 2c -c public localhost:1062 "" NET-SNMP-EXAMPLES-MIB::netSnmpExampleHeartbeatNotification  netSnmpExampleHeartbeatRate i 123456
+```
+
+> Requires the `snmp` package to be installed
 
+# License
 
-Released under the same terms as Sensu (the MIT license). 
+Released under the same terms as Sensu (the MIT license).

data/bin/extension-snmptrap.rb

@@ -4,17 +4,29 @@
 #
 # DESCRIPTION:
 #   Handles incoming SNMP Traps and emits sensu events
-#   Creates an SNMP trap listening to all incoming traps on any interface and triggers events into sensu as JIT clients specifying the source of the event.
+#   Creates an SNMP trap listening to all incoming traps on any interface and
+#   triggers events into sensu as JIT clients specifying the source of the event.
 #
-#   Also able to run as a 'polling' service in either Check or Metrics mode
-#   where values can be directly compared against expectations (eg value > 10)
-#   or where values are sent to Sensu as metrics values for charting or
-#   other purposes.
 #
 #       {
 #        "snmp": { }
 #       }
 #
+#   Default options are;
+#      {
+#        "snmp": {
+#          bind: '0.0.0.0',
+#          port: 1062,
+#          community: 'public',
+#          handler: 'default',
+#          send_interval: 60,
+#          trapdefs_dir: '/etc/sensu/traps.d',
+#          mibs_dir: '/etc/sensu/mibs',
+#          client_socket_bind: settings[:client][:socket][:bind],
+#          client_socket_port: settings[:client][:socket][:port]
+#        }
+#      }
+#
 # OUTPUT:
 #   N/A - Extension submits multiple events of different types based on snmp configuration
 #
@@ -56,16 +68,6 @@ include SNMP
 module Sensu
   module Extension
     class SNMPTrapHandler < Check
-      # assume the /etc/sensu/extensions folder as location for relative
-      data_path = File.expand_path(File.dirname(__FILE__) + '/../mibs')
-
-      DEFAULT_MIB_PATH = nil
-      if File.exist?(data_path)
-        DEFAULT_MIB_PATH = data_path
-      else
-        @logger.info "Could not find default MIB directory, tried:\n  #{data_path}"
-      end
-
       def name
         'SnmpTrapHandler'
       end
@@ -83,7 +85,9 @@ module Sensu
           handler: 'default',
           send_interval: 60,
           trapdefs_dir: '/etc/sensu/traps.d',
-          mibs_dir: '/etc/sensu/mibs'
+          mibs_dir: '/etc/sensu/mibs',
+          client_socket_bind: settings[:client][:socket][:bind],
+          client_socket_port: settings[:client][:socket][:port]
         }
         @options.merge!(@settings[:snmp]) if @settings[:snmp].is_a?(Hash)
         @options
@@ -97,37 +101,50 @@ module Sensu
         }
       end
 
-      def post_init
-        # Setup SNMPTrap
-        @logger.debug "Loading SNMPTrap definitions from #{options[:trapdefs_dir]}"
-        @trapdefs = []
-        Dir.glob(options[:trapdefs_dir] + '/*.json') do |file|
-          # do something with the file here
-          @logger.info file
-          @trapdefs.concat Array(JSON.parse(File.read(file)))
+      def validate
+
+        if options[:client_socket_bind].nil?
+          @logger.warn "couldnt find client socket binding - is it defined? https://sensuapp.org/docs/latest/reference/clients.html#socket-attributes"
+          false
         end
+        true
+      end
 
-        @logger.debug @trapdefs.to_json
+      def post_init
+        if !validate
+          @logger.error "failed to validate the #{name} extension"
+        else
+          # Setup SNMPTrap
+          @logger.debug "loading SNMPTrap definitions from #{options[:trapdefs_dir]}"
+          @trapdefs = []
+          Dir.glob(options[:trapdefs_dir] + '/*.json') do |file|
+            @logger.debug "Reading #{file}..."
+            @trapdefs.concat Array(::JSON.parse(File.read(file)))
+          end
 
-        @mibs = []
-        Dir.glob(options[:mibs_dir] + '/*.yaml') do |file|
-          # do something with the file here
-          @logger.debug "Reading MIB configuration from #{File.basename(file, '.yaml')}"
-          @mibs << File.basename(file, '.yaml')
-        end
-        @logger.debug @mibs.to_json
+          @logger.debug "loaded trapdefs..."
+          @logger.debug @trapdefs.to_json
+
+          @mibs = []
+          Dir.glob(options[:mibs_dir] + '/*.yaml') do |file|
+            # do something with the file here
+            @logger.debug "reading MIB configuration from #{File.basename(file, '.yaml')}"
+            @mibs << File.basename(file, '.yaml')
+          end
+          @logger.debug @mibs.to_json
 
-        start_trap_listener
+          start_trap_listener
+        end
       end
 
       def run(_data = nil, _options = {}, &callback)
-        @logger.warn('SNMP Trap: Run called as a check - this is not supported')
+        @logger.warn('SNMP trap: run called as a check - this is not supported')
         output = 'SNMPHandler extension should not be called as a standalone check'
         callback.call(output, 3)
       end
 
       def start_trap_listener
-        @logger.info('Starting SNMP Trap listener...')
+        @logger.info('starting SNMPTrap listener...')
 
         SNMP::TrapListener.new(Host: options[:bind], Port: options[:port]) do |manager|
           # Need patched Gem to allow the following functions/lookups
@@ -140,13 +157,11 @@ module Sensu
           # @mib = manager.mib
 
           manager.on_trap_v1 do |trap|
-            @logger.info('v1-Trap caught')
-            @logger.info trap.to_json
+            @logger.warn('SNMPTrap caught an snmp v1 trap which not currently handled')
           end
 
           manager.on_trap_v2c do |trap|
-            @logger.info('v2-Trap caught')
-            @logger.info(trap.to_json)
+            @logger.debug('v2-Trap caught')
 
             processed = false
             @trapdefs.each do |trapdef|
@@ -159,16 +174,16 @@ module Sensu
               @logger.debug 'trap ' + trap.trap_oid.inspect
               # only accept configured traps
               if trap.trap_oid == trapdef_oid
-                @logger.info "Processing known v2 trap #{trap.trap_oid}"
+                @logger.info "SNMPTrap is processing a defined snmp v2 trap oid:#{trap.trap_oid}"
                 process_v2c_trap trap, trapdef
                 processed = true
                 break
               end
-              @logger.debug "Ignoring unrecognised trap: #{trap.trap_oid}" unless processed
+              @logger.debug "ignoring unrecognised trap: #{trap.trap_oid}" unless processed
             end
           end
 
-          @logger.info("SNMP Trap listener has started on #{options[:bind]}:#{options[:port]}")
+          @logger.info("SNMPTrap listener has started on #{options[:bind]}:#{options[:port]}")
         end
       end
 
@@ -179,12 +194,18 @@ module Sensu
       def publish_check_result(check)
         # a little risky: we're assuming Sensu-Client is listening on Localhost:3030
         # for submitted results : https://sensuapp.org/docs/latest/clients#client-socket-input
-        @logger.info "Sending SNMP check event: #{check.to_json}"
+        @logger.debug "sending SNMP check event: #{check.to_json}"
 
-        host = settings[:client][:bind] ||= '127.0.0.1'
-        port = settings[:client][:port] ||= '3030'
-        t = TCPSocket.new host, port
-        t.write(check.to_json + "\n")
+        host = options[:client_socket_bind]
+        port = options[:client_socket_port]
+
+        begin
+          @logger.debug "opening connection to #{host}:#{port}"
+          t = TCPSocket.new host, port
+          t.write(check.to_json + "\n")
+        rescue Exception => e
+          @logger.error(e)
+        end
       end
 
       def process_v2c_trap(trap, trapdef)
@@ -192,14 +213,14 @@ module Sensu
         begin
           hostname = Resolv.getname(trap.source_ip)
         rescue Resolv::ResolvError
-          @logger.debug("Unable to resolve name for #{trap.source_ip}")
+          @logger.debug("unable to resolve name for #{trap.source_ip}")
         end
 
         fields = {}
         fields[:source] = trap.source_ip
         fields[:hostname] = hostname
 
-        @logger.debug('Checking trap definition for key/value template pairs')
+        @logger.debug('checking trap definition for key/value template pairs')
         Array(trapdef['trap']).each do |key, value|
           begin
             value = SNMP::ObjectId.new(value)
@@ -211,19 +232,19 @@ module Sensu
           @logger.debug trap.varbind_list.inspect
           val = trap.varbind_list.find { |vb| vb.name == value }
           if val.nil?
-            @logger.warn("trap.#{key} has OID(#{value}) that was not found in incoming trap - Check your configuration")
+            @logger.warn("trap.#{key} has OID(#{value}) that was not found in incoming trap - check your configuration")
           end
-          @logger.debug("Discovered value of #{key} is '#{val}'")
+          @logger.debug("discovered value of #{key} is '#{val}'")
           fields[key] = val.value unless val.nil?
         end
 
-        @logger.debug("Template fields are: #{fields.inspect}")
+        @logger.debug("template fields are: #{fields.inspect}")
 
         # Replace any {template} values in the event with the value of
         # snmp values defined in the traps configuration
         fields.each do |key, value|
           trapdef['event'].each do |k, v|
-            @logger.debug("Looking for #{key} in #{trapdef['event'][k]}")
+            @logger.debug("looking for #{key} in #{trapdef['event'][k]}")
             begin
               trapdef['event'][k] = v.gsub("{#{key}}", value.to_s.gsub('/', '-'))
             rescue

data/lib/sensu-plugins-snmptrap-extension/version.rb

@@ -1,7 +1,7 @@
 module SensuPluginsSnmptrapExtension
   module Version
     MAJOR = 0
-    MINOR = 1
+    MINOR = 2
     PATCH = 0
 
     VER_STRING = [MAJOR, MINOR, PATCH].compact.join('.')

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: sensu-plugins-snmptrap-extension
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
-- Toby Jackson <toby@warmfusion.co.uk>
-- Peter Daugavietis <pdaugavietis@gmail.com>
+- Toby Jackson
+- Peter Daugavietis
 autorequire: 
 bindir: bin
 cert_chain: