netsnmp 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 8014fd377e09fcd49d70da331116b3d66bce52e3
-  data.tar.gz: 9038971c4dd91219e581ddfdfa11d64b062790bf
+SHA256:
+  metadata.gz: faea873fa6ca9eaf4c453c77dc2f897af13b523521344f8e39e72006f1493d23
+  data.tar.gz: 6e671ad1fb6ecb01ddbad7647ce2c01f532537845cd74fcd3db188a8af543010
 SHA512:
-  metadata.gz: b1469577a0aa7719c12fa54eb445b4016f3e44b3caa2d51db8931b18f852256af0482261feeff407e195c0af2cf72d3ddb477ca6062b529f9dd0748e1dd2ffcc
-  data.tar.gz: 31a013f21505b92217c276b33631c52c0cb42c9d493a24b51a3bd190304f4ac67c3a1e921fa59f6f432f8f5b4b6248f68e65581ef4f2c2f7f044968bda57a4ae
+  metadata.gz: 2a49e950ce387bf6c0e41d928b7a2617540990b399814cc5811969cedd4a65483454af203b990e4dcc041aa95cac7cdb19aa2c2fba3c7b16cfb24c424eef5b43
+  data.tar.gz: 007eb164271090585dbcab085a0a4bdef899c8acbb8b79ac43cba99c7b859326b7c2b89c08af03716f24d2980110196ac8f1795b527377fedb178b53ca013055

data/.rubocop.yml

@@ -0,0 +1,11 @@
+inherit_from: .rubocop_todo.yml
+
+AllCops:
+  TargetRubyVersion: 2.3
+
+Layout/IndentHeredoc:
+  Enabled: false
+
+Style/NumericPredicate:
+  Exclude:
+    - lib/netsnmp.rb

data/.rubocop_todo.yml

@@ -0,0 +1,69 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2018-02-07 22:49:11 +0000 using RuboCop version 0.52.1.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+Metrics/BlockLength:
+  Max: 200
+
+# Offense count: 17
+Metrics/AbcSize:
+  Max: 27
+
+# Offense count: 2
+# Configuration parameters: CountComments.
+Metrics/ClassLength:
+  Max: 150
+
+# Offense count: 8
+Metrics/CyclomaticComplexity:
+  Max: 20
+
+# Offense count: 22
+# Configuration parameters: CountComments.
+Metrics/MethodLength:
+  Max: 30
+
+# Offense count: 2
+# Configuration parameters: CountKeywordArgs.
+Metrics/ParameterLists:
+  Max: 7
+
+# Offense count: 1
+Metrics/PerceivedComplexity:
+  Max: 9
+
+# Offense count: 10
+Style/Documentation:
+  Exclude:
+    - 'spec/**/*'
+    - 'test/**/*'
+    - 'lib/netsnmp.rb'
+    - 'lib/netsnmp/encryption/aes.rb'
+    - 'lib/netsnmp/encryption/des.rb'
+    - 'lib/netsnmp/encryption/none.rb'
+    - 'lib/netsnmp/scoped_pdu.rb'
+    - 'lib/netsnmp/session.rb'
+    - 'lib/netsnmp/timeticks.rb'
+
+# Offense count: 8
+# Cop supports --auto-correct.
+# Configuration parameters: Strict.
+Style/NumericLiterals:
+  MinDigits: 11
+
+  # Offense count: 264
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, ConsistentQuotesInMultiline.
+# SupportedStyles: single_quotes, double_quotes
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+# Offense count: 112
+# Configuration parameters: AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, IgnoredPatterns.
+# URISchemes: http, https
+Metrics/LineLength:
+  Max: 189

data/.travis.yml

@@ -5,23 +5,14 @@ services:
 before_install:
   - sudo apt-add-repository multiverse 
   - sudo apt-get update
-  - sudo apt-get install -y sed
-  - sudo apt-get install -y snmp
-  - sudo apt-get install -y libsnmp-dev
-  - sudo apt-get install -y snmp-mibs-downloader 
-  - sudo apt-get install -o Dpkg::Options::="--force-confold" --force-yes -y docker-engine
-
-before_script:
-  - sudo download-mibs 
-  - sudo sed -i 's/^mibs/#mibs/g' /etc/snmp/snmp.conf
-  - spec/support/start_docker.sh
-after_script: spec/support/stop_docker.sh
+  - sudo apt-get install -o Dpkg::Options::="--force-confold" --force-yes -y docker-ce
 
 install:
+  - gem update --system
   - bundle install --path .bundle
 
 script:
-  - bundle exec rake spec:ci
+  - spec/support/specs.sh
 
 language: ruby
 rvm:
@@ -29,8 +20,9 @@ rvm:
   - 2.2
   - 2.3
   - 2.4
+  - 2.5
   - ruby-head
-  - jruby-9.1.7.0
+  - jruby-9.1.15.0
   - jruby-head
   - rbx-2
 matrix:
@@ -38,5 +30,5 @@ matrix:
   - rvm: ruby-head
   - rvm: jruby-head
     # to figure out later
-  - rvm: jruby-9.1.7.0
+  - rvm: jruby-9.1.15.0
   - rvm: rbx-2

data/Gemfile

@@ -1,17 +1,17 @@
+# frozen_string_literal: true
+
 source "https://rubygems.org/"
 ruby RUBY_VERSION
 
 gemspec
 
-gem 'coveralls', require: false
+gem "coveralls", require: false
 
 group :development do
-  gem 'pry'
+  gem "pry"
 end
 
-if RUBY_VERSION < "2.2"
-  gem "nio4r", "~> 1.2"
-end
+gem "nio4r", "~> 1.2" if RUBY_VERSION < "2.2"
 
 platforms :mri do
   gem "pry-byebug", require: false
@@ -19,3 +19,5 @@ platforms :mri do
 end
 
 gem "xorcist"
+
+gem "rubocop", require: false

data/README.md

@@ -1,4 +1,4 @@
-# netsnmp 
+# netsnmp
 
 [![Build Status](https://travis-ci.org/swisscom/ruby-netsnmp.svg?branch=master)](https://travis-ci.org/swisscom/ruby-netsnmp)
 [![Coverage Status](https://coveralls.io/repos/github/swisscom/ruby-netsnmp/badge.svg?branch=master)](https://coveralls.io/github/swisscom/ruby-netsnmp?branch=master)
@@ -11,7 +11,7 @@ The `netsnmp` gem provides a ruby native implementation of the SNMP protocol (v1
 
 Add this line to your application's Gemfile:
 
-```ruby 
+```ruby
 gem 'netsnmp'
 ```
 
@@ -27,7 +27,7 @@ Or install it yourself as:
 $ gem install netsnmp
 ```
 
-## Features 
+## Features
 
 This gem provides:
 
@@ -38,46 +38,48 @@ This gem provides:
 
 ## Why?
 
-If you look for snmp gems in ruby toolbox, you'll find a bunch. 
-You may ask, why not just use one of them? 
+If you look for snmp gems in ruby toolbox, you'll find a bunch.
+You may ask, why not just use one of them?
 
 Most of them only implement v1 and v2, so if your requirement is to use v3, you're left with only 2 choices: [net-snmp](https://github.com/mixtli/net-snmp) (unmantained since 2013) and its follow-up [net-snmp2](https://github.com/jbreeden/net-snmp2), which started as a fork to fix some bugs left unattended. Both libraries wrap the C netsnmp library using FFI, which leaves them vulnerable to the following bugs (experienced in both libraries):
 
-* Dependency of specific versions of netsnmp C package. 
+* Dependency of specific versions of netsnmp C package.
 * Memory Leaks.
 * Doesn't work reliable in ruby > 2.0.0-p576, crashing the VM.
 * Network I/O done by the library, thereby blocking the GVL, thereby making all snmp calls block the whole ruby VM.
-  * This means, multi-threading is impossible. 
+  * This means, multi-threading is impossible.
   * This means, evented I/O is impossible.
 
-All of these issues are resolved here. 
+All of these issues are resolved here.
 
 ## Features
 
 * Client Interface, which supports SNMP v3, v2c, and v1
-* Supports get, getnext, set and walk calls. 
+* Supports get, getnext, set and walk calls.
 * Proxy IO object support (for eventmachine/celluloid-io)
-* Ruby >= 2.1 support
+* Ruby >= 2.1 support (modern)
 * Pure Ruby (no FFI)
 
 ## Examples
 
-You can use the docker container provided under spec/support to test against these examples (the port used in the examples should be the docker external port mapped to port 161). 
+You can use the docker container provided under spec/support to test against these examples (the port used in the examples should be the docker external port mapped to port 161).
 
 ```ruby
 require 'netsnmp'
 
-# example you can test against the docker simulator provided. port attribute might be different. 
+# example you can test against the docker simulator provided. port attribute might be different.
 manager = NETSNMP::Client.new(host: "localhost", port: 33445, username: "simulator",
-                              auth_password: "auctoritas", auth_protocol: :md5, 
+                              auth_password: "auctoritas", auth_protocol: :md5,
                               priv_password: "privatus", priv_protocol: :des,
                               context: "a172334d7d97871b72241397f713fa12")
 
 # SNMP get
-manager.get(oid: "sysName.0") #=> 'tt'
+# sysName.0
+manager.get(oid: "1.3.6.1.2.1.1.0") #=> 'tt'
 
 # SNMP walk
-manager.walk("sysORDescr") do |oid_code, value|
+# sysORDescr
+manager.walk(oid: "1.3.6.1.2.1.1.1").each do |oid_code, value|
   # do something with them  
   puts "for #{oid_code}: #{value}"
 end
@@ -86,18 +88,51 @@ manager.close
 
 # SNMP set
 manager2 = NETSNMP::Client.new(host: "localhost", port: 33445, username: "simulator",
-                               auth_password: "auctoritas", auth_protocol: :md5, 
+                               auth_password: "auctoritas", auth_protocol: :md5,
                                priv_password: "privatus", priv_protocol: :des,
                                context: "0886e1397d572377c17c15036a1e6c66")
 
 # setting to 43, becos yes
-manager2.set("sysUpTimeInstance", 43) 
+# sysUpTimeInstance
+manager2.set("1.3.6.1.2.1.1.3.0", value: 43)
 
 manager2.close
 ```
 
-SNMP v2/v1 examples will be similar (beware of the differences in the initialization attributes). 
+SNMP v2/v1 examples will be similar (beware of the differences in the initialization attributes).
+
+## SNMP Application Types
+
+All previous examples were done specifying primitive types, i.e. unless specified otherwise, it's gonna try to convert a ruby "primitive" type to an ASN.1 primitive type, and vice-versa:
+
+* Integer      -> ASN.1 Integer
+* String      -> ASN.1 Octet String
+* nil         -> ASN.1 Null
+* true, false -> ASN.1 Boolean
+
+That means that, if you pass `value: 43` to the `#set` call, it's going to build a varbind with an ASN.1 Integer. If You issue a `#get` and the response contains an ASN.1 Integer, it's going to return an Integer.
+
+However, SNMP defines application-specific ASN.1 types, for which there is support, albeit limited. Currently, there is support for ip addresses and timeticks.
+
+* IPAddr -> ASN.1 context-specific
 
+If you create an `IPAddr` object (ruby standard library `ipaddr`) and pass it to the `#set` call, it will map to the SNMP content-specific code. If the response of a `#get` call contains an ip address, it will map to an `IPAddr` object.
+
+* NETSNMP::Timeticks -> ASN.1 content-specific
+
+The `NETSNMP::Timeticks` type is internal to this library, but it is a ruby `Numeric` type. You are safe to use it "as a numeric", that is, perform calculations.
+
+
+You can find usage examples [here](https://github.com/swisscom/ruby-netsnmp/blob/master/spec/varbind_spec.rb). If you need support to a missing type, you have the following options:
+
+* Use the `:type` parameter in `#set` calls:
+```ruby
+# as a symbol
+manager.set("somecounteroid", value: 999999, type: :counter64)
+# as the SNMP specific type id, if you're familiar with the protocol
+manager.set("somecounteroid", value: 999999, type: 6)
+```
+* Fork this library, extend support, write a test and submit a PR (the desired solution ;) )
 
 ## Concurrency
 
@@ -106,8 +141,8 @@ In ruby, you are usually adviced not to share IO objects across threads. The sam
 ```ruby
 general_options = { auth_protocol: ....
 routers.map do |r|
-  Thread.start do 
-    NETSNMP::Client.new(general_options.merge(host: r)) do |cl| 
+  Thread.start do
+    NETSNMP::Client.new(general_options.merge(host: r)) do |cl|
       cli.get(oid: "1.6.3.......
 
     end
@@ -115,13 +150,13 @@ routers.map do |r|
 end.each(&:join)
 ```
 
-Evented IO is also supported, in that you can pass a `:proxy` object as an already opened channel of communication to the client. Very important: you have to take care of the lifecycle, as the client will not connect and will not close the object, it will assume no control over it. 
+Evented IO is also supported, in that you can pass a `:proxy` object as an already opened channel of communication to the client. Very important: you have to take care of the lifecycle, as the client will not connect and will not close the object, it will assume no control over it.
 
-When passing a proxy object, you can omit the `:host` parameter. 
+When passing a proxy object, you can omit the `:host` parameter.
 
 The proxy object will have to be a duck-type implementing `#send`, which is a method receiving the sending PDU payload, and return the payload of the receiving PDU.
 
-Here is a small pseudo-code example: 
+Here is a small pseudo-code example:
 
 ```ruby
 # beware, we are inside a warp-speed loop!!!
@@ -136,14 +171,14 @@ end
 proxy.close
 ```
 
-For more information about this subject, the specs test this feature against celluloid-io. An eventmachine could be added, if someone would be kind enough to provide an implementation. 
+For more information about this subject, the specs test this feature against celluloid-io. An eventmachine could be added, if someone would be kind enough to provide an implementation.
 
 ## Performance
 
 
 ### XOR
 
-This library has some workarounds to some missing features in the ruby language, namely the inexistence of a byte array structure. The closest we have is a byte stream presented as a String with ASCII encoding. A method was added to the String class called `#xor` for some operations needed internally. To prevent needless monkey-patches, Refinements have been employed. 
+This library has some workarounds to some missing features in the ruby language, namely the inexistence of a byte array structure. The closest we have is a byte stream presented as a String with ASCII encoding. A method was added to the String class called `#xor` for some operations needed internally. To prevent needless monkey-patches, Refinements have been employed.
 
 If `#xor` becomes at some point the bottleneck of your usage, this gem has also support for [xorcist](https://github.com/fny/xorcist/). You just have to add it to your Gemfile (or install it in the system):
 
@@ -152,12 +187,12 @@ If `#xor` becomes at some point the bottleneck of your usage, this gem has also
 
 gem 'netsnmp'
 
-# or, in the command line 
+# or, in the command line
 
 $ gem install netsnmp      
 ```                        
 
-and `netsnmp` will automatically pick it up. 
+and `netsnmp` will automatically pick it up.
 
 ## Auth/Priv Key
 
@@ -166,7 +201,7 @@ If you'll use this gem often with SNMP v3 and auth/priv security level enabled,
 There is a recommended work-around, but this is only usable **if you are using the same user/authpass/privpass on all the hosts!!!**. Use this with care, then:
 
 ```ruby
-$shared_security_parameters = NETSNMP::SecurityParameters.new(security_level: :authpriv, username: "mustermann", 
+$shared_security_parameters = NETSNMP::SecurityParameters.new(security_level: :authpriv, username: "mustermann",
                                                               auth_protocol: :md5, priv_protocol: :aes, ....
 # this will eager-load the auth/priv_key
 ...
@@ -184,9 +219,9 @@ All encoding/decoding/encryption/decryption/digests are done using `openssl`, wh
 
 ## Tests
 
-This library uses RSpec. The client specs are "integration" tests, in that we communicate with an snmp agent simulator. 
+This library uses RSpec. The client specs are "integration" tests, in that we communicate with an snmp agent simulator.
 
-To start the simulator locally, you'll need docker 1.9 or higher (Why 1.9? ```--build-arg``` parameter support was needed for our builds in the CI. You could use a lower version by providing the proxy environment variables in the Dockerfile directly, provided you don't merge these changes to master, thereby exposing your proxy). 
+To start the simulator locally, you'll need docker 1.9 or higher (Why 1.9? ```--build-arg``` parameter support was needed for our builds in the CI. You could use a lower version by providing the proxy environment variables in the Dockerfile directly, provided you don't merge these changes to master, thereby exposing your proxy).
 
 ```
 > spec/support/start_docker.sh
@@ -217,7 +252,6 @@ There are some features which this gem doesn't support. It was built to provide
 
 * No MIB support (you can only work with OIDs)
 * No server (Agent, in SNMP-ish) implementation.
-* No getbulk support. 
+* No getbulk support.
 
 So if you like the gem, but would rather have these features implemented, please help by sending us a PR and we'll gladly review it.
-

data/Rakefile

@@ -1,6 +1,8 @@
-require 'bundler/gem_tasks'
-require 'rspec/core/rake_task'
-require 'coveralls/rake/task'
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "coveralls/rake/task"
 
 desc "runs the tests and sends to coveralls server"
 Coveralls::RakeTask.new
@@ -10,17 +12,13 @@ RSpec::Core::RakeTask.new
 
 task default: [:spec]
 
-
-
 namespace :spec do
   desc "runs the tests in coverage mode"
   task :coverage do
-    ENV['COVERAGE'] = "true"
+    ENV["COVERAGE"] = "true"
     Rake::Task["spec"].execute
   end
 
   desc "runs tests, check coverage, pushes to coverage server"
-  task :ci => ['spec:coverage', 'coveralls:push']
+  task ci: ["spec:coverage", "coveralls:push"]
 end
-
-

data/lib/netsnmp/client.rb

@@ -1,10 +1,13 @@
 # frozen_string_literal: true
+
+require "timeout"
+
 module NETSNMP
   # Main Entity, provides the user-facing API to communicate with SNMP Agents
   #
   # Under the hood it creates a "session" (analogous to the net-snmp C session), which will be used
   # to proxy all the communication to the agent. the Client ensures that you only write pure ruby and
-  # read pure ruby, not concerning with snmp-speak like PDUs, varbinds and the like. 
+  # read pure ruby, not concerning with snmp-speak like PDUs, varbinds and the like.
   #
   #
   class Client
@@ -14,7 +17,7 @@ module NETSNMP
     # @option options [String, Integer, nil] :version the version of the protocol (defaults to 3).
     #    also accepts common known declarations like :v3, "v2c", etc
     # @option options [Integer] :retries number of retries for each failed PDU (after which it raise timeout error. Defaults to {RETRIES} retries)
-    # @yield [client] the instantiated client, after which it closes it for use. 
+    # @yield [client] the instantiated client, after which it closes it for use.
     # @example Yielding a clinet
     #    NETSNMP::Client.new(host: "241.232.22.12") do |client|
     #      puts client.get(oid: "1.3.6.1.2.1.1.5.0")
@@ -22,25 +25,24 @@ module NETSNMP
     #
     def initialize(**options)
       version = options[:version]
-      version = case version 
-        when Integer then version # assume the use know what he's doing
-        when /v?1/ then 0 
-        when /v?2c?/ then 1 
-        when /v?3/, nil then 3
-      end
+      version = case version
+                when Integer then version # assume the use know what he's doing
+                when /v?1/ then 0
+                when /v?2c?/ then 1
+                when /v?3/, nil then 3
+                end
 
       @retries = options.fetch(:retries, RETRIES)
       @session ||= version == 3 ? V3Session.new(options) : Session.new(options)
-      if block_given?
-        begin
-          yield self
-        ensure
-          close
-        end
+      return unless block_given?
+      begin
+        yield self
+      ensure
+        close
       end
     end
 
-    # Closes the inner section 
+    # Closes the inner section
     def close
       @session.close
     end
@@ -49,23 +51,24 @@ module NETSNMP
     #
     # @see {NETSNMP::Varbind#new}
     #
-    def get(oid_opts)
-      request = @session.build_pdu(:get, oid_opts)
+    def get(*oid_opts)
+      request = @session.build_pdu(:get, *oid_opts)
       response = handle_retries { @session.send(request) }
       yield response if block_given?
-      response.varbinds.first.value
+      values = response.varbinds.map(&:value)
+      values.size > 1 ? values : values.first
     end
 
     # Performs an SNMP GETNEXT Request
-    # 
+    #
     # @see {NETSNMP::Varbind#new}
     #
-    def get_next(oid_opts)
-      request = @session.build_pdu(:getnext, oid_opts)
+    def get_next(*oid_opts)
+      request = @session.build_pdu(:getnext, *oid_opts)
       response = handle_retries { @session.send(request) }
       yield response if block_given?
-      varbind = response.varbinds.first
-      [varbind.oid, varbind.value]
+      values = response.varbinds.map { |v| [v.oid, v.value] }
+      values.size > 1 ? values : values.first
     end
 
     # Perform a SNMP Walk (issues multiple subsequent GENEXT requests within the subtree rooted on an OID)
@@ -74,7 +77,7 @@ module NETSNMP
     #
     # @return [Enumerator] the enumerator-collection of the oid-value pairs
     #
-    def walk(oid: )
+    def walk(oid:)
       walkoid = oid
       Enumerator.new do |y|
         code = walkoid
@@ -84,10 +87,10 @@ module NETSNMP
             get_next(oid: code) do |response|
               response.varbinds.each do |varbind|
                 code = varbind.oid
-                if !OID.parent?(walkoid, code) or 
-                    varbind.value.eql?(:endofmibview) or
-                    code == first_response_code
-                  throw(:walk)             
+                if !OID.parent?(walkoid, code) ||
+                   varbind.value.eql?(:endofmibview) ||
+                   (code == first_response_code)
+                  throw(:walk)
                 else
                   y << [code, varbind.value]
                 end
@@ -102,13 +105,13 @@ module NETSNMP
     # Perform a SNMP GETBULK Request (performs multiple GETNEXT)
     #
     # @param [String] oid the first oid
-    # @param [Hash] options the varbind options 
+    # @param [Hash] options the varbind options
     # @option options [Integer] :errstat sets the number of objects expected for the getnext instance
-    # @option options [Integer] :errindex number of objects repeating for all the repeating IODs. 
+    # @option options [Integer] :errindex number of objects repeating for all the repeating IODs.
     #
     # @return [Enumerator] the enumerator-collection of the oid-value pairs
     #
-    #def get_bulk(oid)
+    # def get_bulk(oid)
     #  request = @session.build_pdu(:getbulk, *oids)
     #  request[:error_status]  = options.delete(:non_repeaters) || 0
     #  request[:error_index] = options.delete(:max_repetitions) || 10
@@ -118,29 +121,29 @@ module NETSNMP
     #      y << [ varbind.oid, varbind.value ]
     #    end
     #  end
-    #end
+    # end
 
     # Perform a SNMP SET Request
     #
     # @see {NETSNMP::Varbind#new}
     #
-    def set(oid_opts)
-      request = @session.build_pdu(:set, oid_opts)
+    def set(*oid_opts)
+      request = @session.build_pdu(:set, *oid_opts)
       response = handle_retries { @session.send(request) }
-      yield response if block_given? 
-      response.varbinds.map(&:value)
+      yield response if block_given?
+      values = response.varbinds.map(&:value)
+      values.size > 1 ? values : values.first
     end
 
-
     private
 
-    # Handles timeout errors by reissuing the same pdu until it runs out or retries. 
+    # Handles timeout errors by reissuing the same pdu until it runs out or retries.
     def handle_retries
       retries = @retries
       begin
         yield
       rescue Timeout::Error => e
-        raise e if retries == 0
+        raise e if retries.zero?
         retries -= 1
         retry
       end