logstash-input-snmp 0.1.0.beta5 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb2edaea9339e4955345a99d3a7c36c3c11eb907d91ee91c7aadb9110a68c215
-  data.tar.gz: bcd78c64a492e9025f277a5139d7517d75e52aa741f8c7314b4b9c51c0285879
+  metadata.gz: 9e8dd0042c7e0a91cfda117ab654b9633159d398e7cd13170a6e301a6de95fc8
+  data.tar.gz: 553989d20b7c2bd9bea0194f7513088dbf8629d2f59a9fbc2a7653af472a6c0a
 SHA512:
-  metadata.gz: 4e6d4213da72a049d9d8f02a3e2ea9e6a93915746595bd14cb5e4c7115f74d549f97c069698090d89fc80a29095f4b399e05362e7449d2c84543cb7be0016d17
-  data.tar.gz: 50441d39a18880a799cbf444af8ddf424d7c348b9f6ef162af195cd221310008b90f5bf58805fdabeea33f21fb33deafd557f64390383a84b175480e90a69017
+  metadata.gz: '0130086878a261d29b22b9bdb35b1607ac7fb7af1ef56207d9b690a7bbbf3416e98336071c06262e5268373834c96037e4175d87e59b6e9a25b4ccb7854afd2e'
+  data.tar.gz: bf4dfa3e025ebabd1eb4f9f064f9fccc79a62b9aab6971b593a4f7a68d6d389881df6069cc2c4a715b9b2e9db2552126068dc6148d1a9a1bc4f162dd6bb26086

data/CHANGELOG.md

@@ -1,3 +1,6 @@
+## 1.0.0
+  - Added improved syntax coercion [#32](https://github.com/logstash-plugins/logstash-input-snmp/pull/32)
+
 ## 0.1.0.beta5
   - Added OPAQUE type coercion [#29](https://github.com/logstash-plugins/logstash-input-snmp/pull/29)
   - Added SNMPv3 support [#27](https://github.com/logstash-plugins/logstash-input-snmp/pull/27)

data/docs/index.asciidoc

@@ -0,0 +1,309 @@
+:plugin: snmp
+:type: input
+:default_codec: plain
+
+// TO DO:  VERIFY default codec!
+
+///////////////////////////////////////////
+START - GENERATED VARIABLES, DO NOT EDIT!
+///////////////////////////////////////////
+:version: %VERSION%
+:release_date: %RELEASE_DATE%
+:changelog_url: %CHANGELOG_URL%
+:include_path: ../../../../logstash/docs/include
+///////////////////////////////////////////
+END - GENERATED VARIABLES, DO NOT EDIT!
+///////////////////////////////////////////
+
+[id="plugins-{type}s-{plugin}"]
+
+=== SNMP input plugin
+
+include::{include_path}/plugin_header.asciidoc[]
+
+==== Description
+
+The SNMP input polls network devices using Simple Network Management Protocol (SNMP)
+to gather information related to the current state of the devices operation.
+
+[id="plugins-{type}s-{plugin}-import-mibs"]
+==== Importing MIBs 
+
+This plugin already includes the IETF MIBs (management information bases) and these do not need to be imported.
+
+Any other MIB will need to be manually imported to provide mapping of the numeric OIDs to MIB field names in the resulting event.
+
+To import a MIB, the OSS https://www.ibr.cs.tu-bs.de/projects/libsmi/[libsmi library] is required.
+libsmi is available and installable on most operating systems.
+
+To import a MIB, you need to first convert the ASN.1 MIB file into a `.dic` file using the libsmi `smidump` command line utility.
+
+Example (using `RFC1213-MIB` file)
+
+[source,sh]
+-----
+$ smidump --level=1 -k -f python RFC1213-MIB > RFC1213-MIB.dic
+-----
+
+Note that the resulting file as output by `smidump` must have the `.dic` extension.
+
+[id="plugins-{type}s-{plugin}-options"]
+==== SNMP Input Configuration Options
+
+This plugin supports the following configuration options plus the <<plugins-{type}s-{plugin}-common-options>> described later.
+
+[cols="<,<,<",options="header",]
+|=======================================================================
+|Setting |Input type|Required
+| <<plugins-{type}s-{plugin}-auth_pass>> |<<password,password>>|No
+| <<plugins-{type}s-{plugin}-auth_protocol>> |<<string,string>>, one of `["md5", "sha", "sha2", "hmac128sha224", "hmac192sha256", "hmac256sha384", "hmac384sha512"]`|No
+| <<plugins-{type}s-{plugin}-get>> |<<array,array>>|No
+| <<plugins-{type}s-{plugin}-hosts>> |<<array,array>>|No
+| <<plugins-{type}s-{plugin}-interval>> |<<number,number>>|No
+| <<plugins-{type}s-{plugin}-mib_paths>> |<<path,path>>|No
+| <<plugins-{type}s-{plugin}-oid_root_skip>> |<<boolean,boolean>>|No
+| <<plugins-{type}s-{plugin}-priv_pass>> |<<password,password>>|No
+| <<plugins-{type}s-{plugin}-priv_protocol>> |<<string,string>>, one of `["des", "3des", "aes", "aes128", "aes192", "aes256"]`|No
+| <<plugins-{type}s-{plugin}-security_level>> |<<string,string>>, one of `["noAuthNoPriv", "authNoPriv", "authPriv"]`|No
+| <<plugins-{type}s-{plugin}-security_name>> |<<string,string>>|No
+| <<plugins-{type}s-{plugin}-walk>> |<<array,array>>|No
+|=======================================================================
+
+Also see <<plugins-{type}s-{plugin}-common-options>> for a list of options supported by all
+input plugins.
+
+[id="plugins-{type}s-{plugin}-get"]
+===== `get` 
+
+Use the `get` option to query for scalar values for the given OID(s).
+One or more OID(s) are specified as an array of strings of OID(s).
+
+* Value type is <<array,array>>
+* There is no default value for this setting
+
+Example
+[source,ruby]
+-----
+input {
+  snmp {
+    get => ["1.3.6.1.2.1.1.1.0", "1.3.6.1.2.1.1.3.0", "1.3.6.1.2.1.1.5.0"]
+    hosts => [{host => "udp:127.0.0.1/161" community => "public"}]
+  }
+}
+-----
+
+[id="plugins-{type}s-{plugin}-hosts"]
+===== `hosts`
+
+The `hosts` option specifies the list of hosts to query the configured `get` and `walk` options.
+
+Each host definition is a hash and must define the `host` key and value.
+`host` must use the format `{tcp|udp}:{ip address}/{port}`, for example `host => "udp:127.0.0.1/161"`
+
+* Value type is <<array,array>>
+* There is no default value for this setting
+
+Each host definition can optionally include the following keys and values:
+
+* `community` the community string, default is `public`.
+* `version` `1`, `2c` or `3`, default is `2c`.
+* `retries` is the number of retries in case of failure, default is `2`.
+* `timeout` is the timeout in milliseconds with a default value of `1000`.
+
+*Specifying all hosts options*
+
+[source,ruby]
+-----
+input {
+  snmp {
+    get => ["1.3.6.1.2.1.1.1.0"]
+    hosts => [{host => "udp:127.0.0.1/161" community => "public" version => "2c"  retries => 2  timeout => 1000}]
+  }
+}
+-----
+
+*Specifying multiple hosts*
+
+[source,ruby]
+-----
+input {
+  snmp {
+    get => ["1.3.6.1.2.1.1.1.0"]
+    hosts => [{host => "udp:127.0.0.1/161" community => "public"}, {host => "udp:192.168.0.1/161" community => "private"}]
+  }
+}
+-----
+
+[id="plugins-{type}s-{plugin}-interval"]
+===== `interval` 
+
+The `interval` option specifies the polling interval in seconds.
+
+* Value type is <<number,number>>
+* Default value is `30`
+
+[id="plugins-{type}s-{plugin}-mib_paths"]
+===== `mib_paths` 
+
+The `mib_paths` option specifies the location of one or more imported MIB files. The value can be either a dir path containing
+the imported MIB `.dic` files or a file path to a single MIB `.dic` file.
+
+* Value type is <<path,path>>
+* There is no default value for this setting
+
+This plugin includes the IETF MIBs.
+If you require other MIBs, you need to import them. See <<plugins-{type}s-{plugin}-import-mibs>>.
+
+[id="plugins-{type}s-{plugin}-oid_root_skip"]
+===== `oid_root_skip` 
+
+The `oid_root_skip` option specifies the  number of OID root digits to ignore in event field name.
+For example, in a numeric OID like "1.3.6.1.2.1.1.1.0" the first 5 digits could be ignored by setting `oid_root_skip => 5`
+which would result in a field name "1.1.1.0". Similarly when a MIB is used an OID such
+"1.3.6.1.2.mib-2.system.sysDescr.0" would become "mib-2.system.sysDescr.0"
+
+* Value type is <<number,number>>
+* Default value is `0`
+
+[id="plugins-{type}s-{plugin}-walk"]
+===== `walk`
+
+Use the `walk` option to retrieve the subtree of information for the given OID(s).
+One or more OID(s) are specified as an array of strings of OID(s).
+
+* Value type is <<array,array>>
+* There is no default value for this setting
+
+Queries the subtree of information starting at the given OID(s).
+
+Example
+[source,ruby]
+-----
+  snmp {
+    walk => ["1.3.6.1.2.1.1"]
+    hosts => [{host => "udp:127.0.0.1/161" community => "public"}]
+  }
+}
+-----
+
+==== SNMPv3 Authentication Options
+
+A **single user** can be configured and will be used for all defined SNMPv3 hosts.
+Multiple snmp input declarations will be needed if multiple SNMPv3 users are required.
+These options are required only if you are using SNMPv3.
+
+[id="plugins-{type}s-{plugin}-auth_pass"]
+===== `auth_pass`
+
+The `auth_pass` option specifies the SNMPv3 authentication passphrase or password
+
+* Value type is <<password,password>>
+* There is no default value for this setting
+
+[id="plugins-{type}s-{plugin}-auth_protocol"]
+===== `auth_protocol`
+
+The `auth_protocol` option specifies the SNMPv3 authentication protocol or type
+
+* Value can be any of: `md5`, `sha`, `sha2`, `hmac128sha224`, `hmac192sha256`, `hmac256sha384`, `hmac384sha512`
+* There is no default value for this setting
+
+[id="plugins-{type}s-{plugin}-priv_pass"]
+===== `priv_pass`
+
+The `priv_pass` option specifies the SNMPv3 encryption password
+
+* Value type is <<password,password>>
+* There is no default value for this setting
+
+[id="plugins-{type}s-{plugin}-priv_protocol"]
+===== `priv_protocol`
+
+The `priv_protocol` option specifies the SNMPv3 privacy/encryption protocol
+
+* Value can be any of: `des`, `3des`, `aes`, `aes128`, `aes192`, `aes256`
+* There is no default value for this setting
+
+[id="plugins-{type}s-{plugin}-security_name"]
+===== `security_name`
+
+The `security_name` option specifies the SNMPv3 security name or user name
+
+* Value type is <<string,string>>
+* There is no default value for this setting
+
+[id="plugins-{type}s-{plugin}-security_level"]
+===== `security_level`
+
+The `security_level` option specifies the SNMPv3 security level between Authentication, No Privacy; Authentication, Privacy; or no Authentication, no Privacy
+
+* Value can be any of: `noAuthNoPriv`, `authNoPriv`, `authPriv`
+* There is no default value for this setting
+
+==== More configuration examples
+
+*Using both `get` and `walk` in the same poll cycle for each host(s)*
+
+[source,ruby]
+-----
+input {
+  snmp {
+    get => ["1.3.6.1.2.1.1.1.0", "1.3.6.1.2.1.1.3.0", "1.3.6.1.2.1.1.5.0"]
+    walk => ["1.3.6.1.2.1.1"]
+    hosts => [{host => "udp:127.0.0.1/161" community => "public"}]
+  }
+}
+-----
+
+*Specifying all global options* 
+
+[source,ruby]
+-----
+input {
+  snmp {
+    get => ["1.3.6.1.2.1.1.1.0"]
+    hosts => [{host => "udp:127.0.0.1/161"}]
+    
+    mib_paths => ["path/to/converted/mibfile.dic"]
+    oid_root_skip => 0
+    interval => 30
+  }
+}
+-----
+
+==== Polled host information
+
+All the polled host information is stored in the event `@metadata`:
+
+* `[@metadata][host_protocol]` : `udp` or `tcp`
+* `[@metadata][host_address]` : host address for example `127.0.0.1`
+* `[@metadata][host_port]` : host port (for example `161`)
+* `[@metadata][host_community]` : community string for example `public`
+
+
+By default, a `host` field is added to the event with the `[@metadata][host_address]` value.
+
+[source,ruby]
+-----
+config :add_field, :validate => :hash, :default => { "host" => "%{[@metadata][host_address]}" }
+-----
+
+You can customize the format and content of the `host` field by specifying an alternate `add_field`. 
+
+Example
+[source,ruby]
+-----
+input {
+  snmp {
+    get => ["1.3.6.1.2.1.1.1.0"]
+    hosts => [{host => "udp:127.0.0.1/161"}]
+    
+    add_field => {host => "%{[@metadata][host_protocol]}:%{[@metadata][host_address]}/%{[@metadata][host_port]},%{[@metadata][host_community]}"}
+  }
+}
+-----
+
+[id="plugins-{type}s-{plugin}-common-options"]
+include::{include_path}/{type}.asciidoc[]
+
+:default_codec!:

data/lib/logstash/inputs/snmp/base_client.rb

@@ -1,6 +1,8 @@
 require "java"
 require "logstash-input-snmp_jars.rb"
 
+require "logstash/util/loggable"
+
 java_import "org.snmp4j.CommunityTarget"
 java_import "org.snmp4j.PDU"
 java_import "org.snmp4j.ScopedPDU"
@@ -25,6 +27,7 @@ module LogStash
   end
 
   class BaseSnmpClient
+    include LogStash::Util::Loggable
 
     def initialize(protocol, address, port, retries, timeout, mib)
       transport = case protocol.to_s
@@ -124,10 +127,12 @@ module LogStash
           NULL_STRING
         when BER::OPAQUE
           variable.toString
-        when BER::NOSUCHOBJECT
-          "Error: No Such Instance currently exists at this OID"
+        when BER::NOSUCHOBJECT, BER::NOSUCHINSTANCE
+          "error: no such instance currently exists at this OID"
         else
-          raise(SnmpClientError, "unknown variable syntax #{variable_syntax}, #{variable.getSyntaxString}")
+          msg = "error: unknown variable syntax #{variable_syntax}, #{variable.getSyntaxString}"
+          logger.error(msg)
+          msg
       end
     end
 

data/logstash-input-snmp.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name          = 'logstash-input-snmp'
-  s.version       = '0.1.0.beta5'
+  s.version       = '1.0.0'
   s.licenses      = ['Apache-2.0']
   s.summary       = "SNMP input plugin"
   s.description   = "This gem is a Logstash plugin required to be installed on top of the Logstash core pipeline using $LS_HOME/bin/logstash-plugin install gemname. This gem is not a stand-alone program"

data/spec/inputs/snmp/base_client_spec.rb

@@ -0,0 +1,38 @@
+# encoding: utf-8
+require "logstash/devutils/rspec/spec_helper"
+require "logstash/inputs/snmp/base_client"
+
+java_import "org.snmp4j.smi.AbstractVariable"
+java_import "org.snmp4j.smi.SMIConstants"
+
+module LogStash
+
+  class TestableBaseSnmpClient < BaseSnmpClient
+    def coerce(*args)
+      super(*args)
+    end
+  end
+
+  describe BaseSnmpClient do
+
+    subject { TestableBaseSnmpClient.new(*client_options) }
+
+    context "coercion" do
+      let(:mib) { SnmpMib.new }
+      let(:client_options) {["udp", "127.0.0.1", "161", 2, 1000, mib]}
+
+      it "should handle BER::NOSUCHINSTANCE" do
+        v = AbstractVariable.create_from_syntax(SMIConstants::EXCEPTION_NO_SUCH_INSTANCE)
+        expect(v.get_syntax).to eq(BER::NOSUCHINSTANCE)
+        expect(subject).to receive(:logger).never
+        expect(subject.coerce(v)).to eq("error: no such instance currently exists at this OID")
+      end
+
+      it "should log on unsupported coercion" do
+        v = AbstractVariable.create_from_syntax(SMIConstants::EXCEPTION_END_OF_MIB_VIEW )
+        expect(subject).to receive(:logger).exactly(1).times.and_call_original
+        expect(subject.coerce(v)).to eq("error: unknown variable syntax 130, EndOfMibView")
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: logstash-input-snmp
 version: !ruby/object:Gem::Version
-  version: 0.1.0.beta5
+  version: 1.0.0
 platform: ruby
 authors:
 - Elasticsearch
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2018-10-03 00:00:00.000000000 Z
+date: 2018-10-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   requirement: !ruby/object:Gem::Requirement
@@ -106,6 +106,7 @@ files:
 - Gemfile
 - LICENSE
 - README.md
+- docs/index.asciidoc
 - lib/logstash-input-snmp_jars.rb
 - lib/logstash/inputs/snmp.rb
 - lib/logstash/inputs/snmp/base_client.rb
@@ -413,6 +414,7 @@ files:
 - logstash-input-snmp.gemspec
 - spec/fixtures/RFC1213-MIB.dic
 - spec/fixtures/collision.dic
+- spec/inputs/snmp/base_client_spec.rb
 - spec/inputs/snmp/mib_spec.rb
 - spec/inputs/snmp_spec.rb
 - vendor/jar-dependencies/org/snmp4j/snmp4j/2.5.11/snmp4j-2.5.11.jar
@@ -434,9 +436,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project:
 rubygems_version: 2.6.13
@@ -446,5 +448,6 @@ summary: SNMP input plugin
 test_files:
 - spec/fixtures/RFC1213-MIB.dic
 - spec/fixtures/collision.dic
+- spec/inputs/snmp/base_client_spec.rb
 - spec/inputs/snmp/mib_spec.rb
 - spec/inputs/snmp_spec.rb