mm_json_client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 946734877ba960aefa97bf9a59279468c50b3afe
+  data.tar.gz: 73520ee1beabd428543aaae65a13e4f918aef6e4
+SHA512:
+  metadata.gz: 4d8cea7e5fc454914d0536b0b87d2be6628aad3b2332f301a98bdafaba15d4f0e6c7a642c9a5da1c8f94cd0ff6a8fbf0e84ab2085eae10920829b010a3020980
+  data.tar.gz: 773b74328b2e3f6f7051942e35a56983390ad5ed5adf9830df163548ac60b48e53db2a9f2233a1fd97e20c61041ed7c956335469b46e6f730388148acbd1a034

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+  - 2.0.0
+  - 2.2
+before_install: gem install bundler -v 1.10.6

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in mm_json_client.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,22 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+## Uncomment and set this to only include directories you want to watch
+# directories %w(app lib config test spec features) \
+#  .select{|d| Dir.exists?(d) ? d : UI.warning("Directory #{d} does not exist")}
+
+## Note: if you are using the `directories` clause above and you are not
+## watching the project directory ('.'), then you will want to move
+## the Guardfile to a watched dir and symlink it back, e.g.
+#
+#  $ mkdir config
+#  $ mv Guardfile config/
+#  $ ln -s config/Guardfile .
+#
+# and, you'll have to watch "config/Guardfile" instead of "Guardfile"
+guard :rspec, cmd: 'bundle exec rspec' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$}) { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch(%r{^generators/(.+)\.rb$}) { |m| "spec/generators/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb') { 'spec' }
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Eric Wannemacher
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,151 @@
+[![Build Status](https://travis-ci.org/ewannema/mm_json_client.svg?branch=master)](https://travis-ci.org/ewannema/mm_json_client)
+
+# MmJsonClient
+
+The MmJsonClient gem is used to access the Men and Mice IPAM API using the
+JSON-RPC format that was first made available in version 6.6.
+
+In order to minimize run time dependencies this gem includes API definition
+files that define the enumerations, methods and types available when using the
+gem. The API definition has been built from the version 7.1.5 WSDL so methods
+available in your installation may differ slightly. Instructions will be coming
+on how to build your own API definition files and use them instead.
+
+## Usage
+
+### Basic Connection Setup
+
+```ruby
+require 'mm_json_client'
+client = MmJsonClient::Client.new(server: 'my-ipam.example.com',
+                                  username: 'demo',
+                                  password: 'demo')
+client.login
+```
+
+Optional parameters to ```Client.new``` are:
+
+| Parameter    | Values     | Purpose |
+| -----------  | ---------- | ------- |
+|endpoint:     | string     | The URI for the web service. Defaults to /_mmwebext/mmwebext.dll?Soap. |
+|open\_timeout:| integer    | Seconds to wait for the initial connection to time out. Defaults to 10.|
+|port:         | integer    | The TCP port for the connection. Defaults to 80 or 443 if SSL is enabled. |
+|proxy:        | string     | The M&M API server. Defaults to the same as the server: parameter. |
+|ssl:          | true/false | Use SSL for the connection. Defaults to false.|
+|verify\_ssl:  | true/false | Whether to validate SSL certificates. Defaults to true.|
+
+### Advanced Connection Setup
+
+The client can optionally take an array of servers for the ```proxy:```
+parameter. This allows you to have redundant API servers without a load
+balancer.
+
+This also allows you to handle the case where the web server is running
+on the same servers as the Central service in a cluster configuration.
+This is important, because in this architecture the web component
+connects to the local server instead of using the DNS round robin entry
+and if you pick the inactive server then you will receive an error about
+operations being disabled.
+
+```ruby
+# When you have multiple web servers that are not behind a load balancer.
+client = MmJsonClient::Client.new(proxy: ['my-ipam01.example.com',
+                                          'my-ipam02.example.com'],
+                                  server: 'ipam-cluster-name.example.com',
+                                  username: 'demo',
+                                  password: 'demo')
+
+# When you have the web role on the M&M central servers in a cluster and need
+# to make sure you can connect to a functioning one.
+client = MmJsonClient::Client.new(proxy: ['my-ipam01.example.com',
+                                          'my-ipam02.example.com'],
+                                  server: 'localhost',
+                                  username: 'demo',
+                                  password: 'demo')
+```
+
+### Case Conversion
+
+Methods, parameters, and values returned from the API use snake case instead of
+camel case as listed in the M&M API docs. Class and enumeration names still use
+Pascal case.
+
+### Making Requests
+
+The methods in the M&M API will be available directly on the client. Any
+required or optional parameters can be included as a hash. The client will
+return a response object that matches what is in the API docs.
+
+### Retrieving Data
+
+```ruby
+# Get all of the DNS zones
+response = client.get_dns_zones
+puts "Found #{response.total_results} zones on the server."
+puts "The first one is #{response.dns_zones.first.name}."
+
+# Search for a particular zone
+response = client.get_dns_zones(filter: 'name:^demo.example.com.$')
+puts "Found #{response.total_results} zones on the server."
+puts "The first one is #{response.dns_zones.first.name}."
+
+# Get all sub-zones from a particular zone.
+response = client.get_dns_zones(filter: 'name:example.com.$')
+puts "Found #{response.total_results} zones on the server."
+puts "The first one is #{response.dns_zones.first.name}."
+
+# Get a single dns zone by reference.
+response = client.get_dns_zone(dns_zone_ref: '{#4-#1000}')
+zone = response.dns_zone
+puts "The zone name is #{zone.name}."
+```
+
+### Making Changes
+
+When you need to create a type to use as a parameter to a method you will
+instantiate it, modify it as necessary and then pass it in.
+
+```ruby
+new_user = MmJsonClient::User.new
+new_user.name = 'demouser'
+new_user.password = 'password'
+new_user.authentication_type = 'Internal'
+
+# or
+
+new_user = MmJsonClient::User.new(name: 'demouser',
+                                  password: 'password',
+                                  authentication_type: 'Internal')
+
+# and then
+client.add_user(user: new_user)
+```
+
+### Enumerated Values
+
+Some fields in the API such as AuthenticationType are enumerated values. To
+see valid values for the enumation use the ```.values``` method.
+
+```ruby
+MmJsonClient::Enums::AuthenticationType.values
+=> ["Internal", "AD", "ADGroup", "RADIUS"]
+```
+
+### Learning and Exploration
+
+There are some [examples](examples/) in this repository.
+
+Check out the SOAP API docs on your server. Although this gem is using the
+JSON-RPC API, the methods, types, enumerations and responses are the same.
+
+If you have completion enabled in your IRB session you will be able to complete
+on method, type, and enumeration names.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/ewannema/mm_json_client.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+

data/Rakefile

@@ -0,0 +1,33 @@
+require 'bundler/gem_tasks'
+require_relative 'generators/enum_def_generator'
+require_relative 'generators/method_def_generator'
+require_relative 'generators/type_def_generator'
+require 'rspec/core/rake_task'
+require 'wasabi'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec
+
+namespace :generate do
+  desc 'Generate a type definition file from a WSDL.'
+  task :type_def do
+    ARGV.each { |a| task a.to_sym {} }
+    generator = MmJsonClient::Generators::TypeDefGenerator.new
+    generator.generate(ARGV[1], ARGV[2])
+  end
+
+  desc 'Generate an enum definition file from a WSDL.'
+  task :enum_def do
+    ARGV.each { |a| task a.to_sym {} }
+    generator = MmJsonClient::Generators::EnumDefGenerator.new
+    generator.generate(ARGV[1], ARGV[2])
+  end
+
+  desc 'Generate an method definition file from a WSDL.'
+  task :method_def do
+    ARGV.each { |a| task a.to_sym {} }
+    generator = MmJsonClient::Generators::MethodDefGenerator.new
+    generator.generate(ARGV[1], ARGV[2])
+  end
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'mm_json_client'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/examples/claim_next_free_ip.rb

@@ -0,0 +1,73 @@
+#!/usr/bin/env ruby
+
+require 'mm_json_client'
+
+#######################################
+# Configuration values from somewhere #
+#######################################
+server = 'my-ipam.example.com'
+username = 'admin'
+password = 'password'
+
+# Options for finding the IP.
+ping_verify = false # try to ping the IP address
+claim_time = 30     # seconds to temporarily claim the record to avoid
+                    #   race conditions
+exclude_dhcp = true # exclude DHCP ranges from available IPs
+
+ip_range = '10.20.30.0/24' # The range to pull the IP from
+
+#######################################
+
+client = MmJsonClient::Client.new(server: server,
+                                  username: username,
+                                  password: password)
+client.login
+
+#######################
+# Get the IP range
+#######################
+response = client.get_ranges(filter: "name:^#{ip_range}$")
+raise "IP Range #{ip_range} not found" if response.total_results == 0
+range = response.ranges.first
+
+###############################################
+# Get the first available address in the range
+###############################################
+response = client.get_next_free_address(range_ref: range.ref,
+                                        ping: ping_verify,
+                                        exclude_dhcp: exclude_dhcp,
+                                        temporary_claim_time: claim_time)
+ip_address = response.address
+
+###############################################
+# Get the corresponding IPAM record for the IP
+###############################################
+response = client.get_ipam_records(range_ref: range.ref,
+                                   limit: 1,
+                                   filter: "address:^#{ip_address}$")
+raise "No IPAM record for #{ip_address}" if response.total_results == 0
+ipam_record = response.ipam_records.first
+
+###############################################
+# Get a deep copy of the IPAM record to update
+# and mark it IPAM record as claimed.
+###############################################
+updated_ipam_record = ipam_record.deep_copy
+updated_ipam_record.state = 'Claimed'
+
+response = client.set_ipam_record(ipam_record_before: ipam_record,
+                                  ipam_record_after: updated_ipam_record)
+unless response.errors.empty?
+  raise "Unable to claim the IPAM record. Errors #{response.errors.inspect}"
+end
+
+###################################################
+# Verify that the IPAM record is marked as claimed
+###################################################
+response = client.get_ipam_record(addr_ref: ipam_record.addr_ref)
+if response.ipam_record.state == 'Claimed'
+  puts "#{ip_address} was successfully claimed."
+else
+  raise 'Failed to claim an IP address.'
+end

data/examples/register_dns.rb

@@ -0,0 +1,37 @@
+#!/usr/bin/env ruby
+
+require 'mm_json_client'
+
+#######################################
+# Configuration values from somewhere #
+#######################################
+server = 'my-ipam.example.com'
+username = 'admin'
+password = 'password'
+
+ip_address = '10.20.30.2'
+dns_zone_name = 'example.com.'
+dns_name = 'gemdemo'
+
+#######################################
+
+client = MmJsonClient::Client.new(server: server,
+                                  username: username,
+                                  password: password)
+client.login
+
+#######################
+# Get the DNS Zone
+#######################
+response = client.get_dns_zones(filter: "name:^#{dns_zone_name}$")
+raise "DNS Zone #{dns_zone_name} not found" if response.total_results == 0
+dns_zone = response.dns_zones.first
+
+dns_record = MmJsonClient::DNSRecord.new(name: dns_name, type: 'A', ttl: nil,
+                                         data: ip_address, enabled: true,
+                                         dns_zone_ref: dns_zone.ref)
+
+response = client.add_dns_record(dns_record: dns_record)
+raise 'Unable to add the DNS record.' unless response.ref
+
+puts "Registered #{dns_name}.#{dns_zone_name} with IP #{ip_address}"

data/examples/release_ip.rb

@@ -0,0 +1,59 @@
+#!/usr/bin/env ruby
+
+require 'mm_json_client'
+
+#######################################
+# Configuration values from somewhere #
+#######################################
+server = 'my-ipam.example.com'
+username = 'admin'
+password = 'password'
+
+ip_range = '10.20.30.0/24' # The range the IP is in
+ip_address = '10.20.30.2'
+
+#######################################
+
+client = MmJsonClient::Client.new(server: server,
+                                  username: username,
+                                  password: password)
+client.login
+
+#######################
+# Get the IP range
+#######################
+response = client.get_ranges(filter: "name:^#{ip_range}$")
+raise "IP Range #{ip_range} not found" if response.total_results == 0
+range = response.ranges.first
+
+###############################################
+# Get the corresponding IPAM record for the IP
+###############################################
+response = client.get_ipam_records(range_ref: range.ref,
+                                   limit: 1,
+                                   filter: "address:^#{ip_address}$")
+raise "No IPAM record for #{ip_address}" if response.total_results == 0
+ipam_record = response.ipam_records.first
+
+###############################################
+# Get a deep copy of the IPAM record to update
+# and mark it IPAM record as free
+###############################################
+updated_ipam_record = ipam_record.deep_copy
+updated_ipam_record.state = 'Free'
+
+response = client.set_ipam_record(ipam_record_before: ipam_record,
+                                  ipam_record_after: updated_ipam_record)
+unless response.errors.empty?
+  raise "Unable to release the IPAM record. Errors #{response.errors.inspect}"
+end
+
+###################################################
+# Verify that the IPAM record is marked as free
+###################################################
+response = client.get_ipam_record(addr_ref: ipam_record.addr_ref)
+if response.ipam_record.state == 'Free'
+  puts "#{ip_address} was successfully released."
+else
+  raise 'Failed to release the IP address.'
+end