shopify-junos-ez-stdlib 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 35f03b58ce9cfea7aee6a2bf7cb00f69721692d8
+  data.tar.gz: a38199a944c32a844c185d01508d9e704de28744
+SHA512:
+  metadata.gz: 032c27f113348d914b8441470bf784efdb34acbbea615d5d7d5612fd7620b72c7273dc88414aac38a39d1356f7ac45412bbbf3ab7c8511aa75b0b4f08936aff9
+  data.tar.gz: 3a947882c3ca848b08daea12cbe66ab104536ebbec5ac0473db3f26d737f63025e12e3d72e0080927c3f5fe63694b2a6ca5a54734f8af598fa62d805f53dec66

data/CHANGELOG.md

@@ -0,0 +1,91 @@
+# 2013-April
+
+  0.0.10: 2013-04-26
+  
+    Initial release of code into RubyGems.  Code tested on EX and SRX-branch. Consider this code
+    as "early-adopter".  Comments/feedback is welcome and appreciated.
+
+  0.0.11: 2013-04-26
+  
+    Updated Junos::Ez::RE::Utils
+      #memory changed :procs from Hash to Array  
+      #users changed return from Hash to Array
+    
+  0.0.12: 2013-04-26
+  
+    Updated Junos::Ez::FS:Utils#ls to include :symlink information
+    Adding Junos::Ez::Users::Provider for login management
+    Adding Junos::Ez::UserAuths::Provider for SSH-key management
+    
+  0.0.14: 2013-04-28
+  
+    Completed initial documentation.  Still more work to be done with these files
+    but the "enough to get started" information is now available
+    
+# 2013-May    
+
+  0.0.15: 2013-05-02
+  
+    L2ports - added support for framework to read [edit vlans] stanza to recognize interfaces configured
+    there vs. under [edit interfaces]
+    
+    IPports - added :acl_in and :acl_out for stateless ACL filtering.  added .status method to return
+    runtime status information about the port
+    
+    RE::Utils - misc updates, and documentation
+
+  0.0.16: 2013-05-03
+  
+    RE::Utils - added support for license-key management.  Renamed "software" methods from "xxx_software"
+    to "software_xxx" to be consistent with other naming usage.  Updated docs.
+  
+  0.0.17: 2013-05-05
+  
+    FS::Utils - updated docs.  fixed methods so that all "error" scenarios raise IOError excaptions.
+  
+  0.1.0: 2013-05-06
+  
+    All docs and code _finished_ for the inital release of code.  Always more to do, but at this
+    point, declaring the framework "good for early adopter testing".  Looking forward to bug-reports,
+    please open issues against this repo.  Thank you!
+    
+  0.1.1: 2013-05-29
+  
+    Fixed a small bug in fact gathering for hardwaremodel
+  
+# 2013-July
+
+  0.1.2: 2013-07-04
+  
+    Fixed issue#3.  Previously this gem would not work with non-VC capable EX switches.  Updated
+    the `facts/version.rb` file to handle these devices.  Also added a new fact `:vc_capable` that
+    is set to `true` if the EX can support virtual-chassis, and `false` if it cannot.
+
+# 2013-Aug
+
+  0.2.0: 
+  
+    Fixed issue #6.  Added support for EX4300 platform.  Added new provider for Link Aggregation Group
+    resources (LAGports)
+
+# 2016-March
+
+  1.0.0:
+
+    Fixed issues
+      Issue #17 Add support for OCX device.
+      Issue #20 "under development" error is thrown while importing the interface_create recipe from the Chef-Server.
+      Issue #22 "netdev_vlan" resource action delete is not working fine while invoking from the JUNOS Chef-Client.
+      Issue #23 RPC command error: commit-configuration is getting thrown on Invoking the "netdev_lag" resource from
+                 JUNOS Chef Client.
+      Issue #27 Duplicate declaration of lag configuration in a recipe is giving NoMethodError: undefined method
+                 `properties' for nil:NilClass.
+      Issue #30 Error in rerunning netdev_lag interface.
+      Issue #33 undefined method `properties' for nil:NilClass error is thrown if the backup RE is unreachable.
+      Issue #35 Error in running chef client from Backup RE.
+      Issue #39 Getting 'Junos::Ez::NoProviderError' error on qfx device.
+      Issue #42 Raise exception to handle warnings in <error-severity>.
+
+    Enhancement
+      * Add support for configuring l2_interface on MX device.
+      * Add support for provider 'group' for configuring JUNOS groups.

data/LICENSE

@@ -0,0 +1,26 @@
+LICENSE (BSD-2)
+===============
+Copyright (c) 2013, Jeremy Schulman, Juniper Networks
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+    Redistributions of source code must retain the above copyright notice,
+    this list of conditions and the following disclaimer.
+
+    Redistributions in binary form must reproduce the above copyright notice,
+    this list of conditions and the following disclaimer in
+    the documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,199 @@
+# OVERVIEW
+
+Ruby framework to support Junos OS based device management automation.  
+
+This is the "standard library" or "core" set of functionality that should work on most/all Junos OS based devices.  
+
+This framework is build on top of the NETCONF gem which uses XML as the fundamental data-exchange.  So no 
+"automating the CLI" or using SNMP.  The purpose of this framework is to **enable automation development 
+without requiring specific Junos XML knowledge**.
+
+Further documentation can be found in the *docs* subdirectory.
+
+# FRAMEWORK
+
+The framework is comprised of these basic eloements:
+
+  - Facts: 
+
+    A Hash of name/value pairs of information auto-collected.  Fact values can be Hash structures as well
+    so you can have deeply nested fact data.  You can also define your own facts in addition to the "stdlib" facts.
+    The facts are used by the framework to create a platform indepent layer of abstraction.  This means
+    that managing a VLAN, for example, is the same regardless of the underlying hardware platofrm (EX, QFX,
+    MX, SRX, ...)
+    
+  - Resources: 
+
+    Resources allow you to easily configure and perform operational functions on specific items within Junos, 
+    for example VLANs, or switch ports.  A resource has *properties* that you manipuate as Hash.  You can
+    interact with Junos using resource methods like `read!`, `write!`, `delete!`, `activate!`, `deactivate!`, etc. 
+    For a complete listing of resource methods, refer to the *docs* directory
+    
+  - Providers:
+
+    Providers allow you to manage a collection of resource, and most commonly, select a resource.  
+    The purpose of a provider/resource is to automate the life-cycle of common changes, like adding
+    VLANs, or ports to a VLAN.  A provider also allows you to obtain a `list` of resources 
+    (Array of *names*) or a `catalog` (Hash of resource properties).  Providers may include resource 
+    specific functionality, like using complex YAML/Hash data for easy import/export and provisioning 
+    with Junos.  If you need the ability to simply apply config-snippets that you do not need to model
+    as resources (as you might for initial device commissioning), the Utilities library is where you 
+    want to start.
+  
+  - Utilities:
+
+    Utilities are simply collections of functions.  The **configuration** utilities, for example, will
+    allow you to easily push config snippets in "curly-brace", "set", or XML formats.  Very useful
+    for unmanaged provider/resources (like initial configuration of the device).  The
+    **routing-engine** utilities, for example, will allow you to easily upgrade software, check
+    memory usage, and do `ping` operations.
+  
+# EXAMPLE USAGE
+  
+```ruby
+require 'pp'
+require 'net/netconf/jnpr'
+require 'junos-ez/stdlib'
+
+unless ARGV[0]
+   puts "You must specify a target"
+   exit 1
+end
+
+# login information for NETCONF session 
+login = { :target => ARGV[0], :username => 'jeremy',  :password => 'jeremy1',  }
+
+## create a NETCONF object to manage the device and open the connection ...
+
+ndev = Netconf::SSH.new( login )
+print "Connecting to device #{login[:target]} ... "
+ndev.open
+puts "OK!"
+
+## Now bind providers to the device object. The 'Junos::Ez::Provider' must be first.
+## This will retrieve the device 'facts'.  The other providers allow you to define the 
+## provider variables; so this example is using 'l1_ports' and 'ip_ports', but you could name 
+## them what you like, yo!
+
+Junos::Ez::Provider( ndev )
+Junos::Ez::L1ports::Provider( ndev, :l1_ports )
+Junos::Ez::IPports::Provider( ndev, :ip_ports )
+Junos::Ez::Config::Utils( ndev, :cu )
+
+# -----------------------------------------------------------
+# Facts ...
+# -----------------------------------------------------------
+
+# show the device softare version fact
+pp ndev.fact :version
+
+# show the device serial-number face
+pp ndev.fact :serialnumber
+
+# get a list of all available facts (Array)
+pp ndev.facts.list
+
+# get a hash of all facts and their associated values
+pp ndev.facts.catalog
+
+# -----------------------------------------------------------
+# Layer 1 (physical ports) Resources ...
+# -----------------------------------------------------------
+
+pp ndev.l1_ports.list
+pp ndev.l1_ports.catalog
+
+# select port 'ge-0/0/0' and display the contents
+# of the properties (like port, speed, description)
+
+ge_0 = ndev.l1_ports['ge-0/0/0']
+pp ge_0.to_h
+
+# change port to disable, this will write the change
+# but not commit it.
+
+ge_0[:admin] = :down
+ge_0.write!
+
+# show the diff of the change to the screen
+
+puts ndev.cu.diff?
+
+# now rollback the change, since we don't want to save it.
+
+ndev.cu.rollback!
+
+ndev.close
+```
+  
+# PROVIDERS
+
+Providers manage access to individual resources and their associated properties.  Providers/resources exists
+for managing life-cycle common changes that you generally need as part of a larger workflow process.  For more
+documentation on Providers/Resources, see the *docs* directory.
+
+  - L1ports: Physical port management
+  - L2ports: Ethernet port (VLAN) management
+  - Vlans: VLAN resource management
+  - IPports: IP v4 port management
+  - StaticHosts: Static Hosts [system static-host-mapping ...]  
+  - StaticRoutes: Static Routes [routing-options static ...] 
+  - Group: JUNOS groups management 
+
+# UTILITIES
+
+  - Config:
+    
+    These functions allow you to load config snippets, do commit checks, look at config diffs, etc.
+    Generally speaking, you would want to use the Providers/Resources framework to manage specific 
+    items in the config.  This utility library is very useful when doing the initial commissioning
+    process, where you do not (cannot) model every aspect of Junos.  These utilities can also be
+    used in conjunction with Providers/Resources, specifically around locking/unlocking and committing
+    the configuration.
+  
+  - Filesystem:
+  
+    These functions provide you "unix-like" commands that return data in Hash forms rather than
+    as string output you'd normally have to screen-scraps.  These methods include `ls`, `df`, `pwd`,
+    `cwd`, `cleanup`, and `cleanup!`
+
+  - Routing-Engine:
+  
+    These functions provide a general collection to information and functioanlity for handling 
+    routing-engine (RE) processes.  These functions `reboot!`, `shutdown!`, `install_software!`, 
+    `ping`.  Information gathering such as memory-usage, current users, and RE status information
+    is also made available through this collection.
+
+# DEPENDENCIES
+
+  * gem netconf
+  * Junos OS based products
+  
+# INSTALLATION 
+
+  * gem install junos-ez-stdlib
+
+# CONTRIBUTORS
+  Juniper Networks is actively contributing to and maintaining this repo. Please contact jnpr-community-netdev@juniper.net 
+  for any queries.
+  
+  Contributors:
+  [John Deatherage](https://github.com/routelastresort), [Nitin Kumar](https://github.com/vnitinv),
+  [Priyal Jain](https://github.com/jainpriyal), [Ganesh Nalawade](https://github.com/ganeshnalawade)
+  
+  Former Contributors:  
+  [Jeremy Schulman](https://github.com/jeremyschulman)
+
+# LICENSES
+
+   BSD-2, See LICENSE file
+
+# SUPPORT
+
+Support for this software is made available exclusively through Github repo issue tracking.  You are also welcome to contact the CONTRIBUTORS directly via their provided contact information.  
+
+If you find a bug, please open an issue against this repo.
+
+If you have suggestions or ideas, please write them up and add them to the "SUGGESTION-BOX" folder of this repo (via pull request).  This way we can share the ideas with the community and crowdsource for feature delivery.
+
+Thank you!

data/docs/Facts.md

@@ -0,0 +1,192 @@
+# FACT KEEPING
+
+This framework is *fact based*, meaning that the provider libraries will have access to information about each
+target.  Facts enable the framework to abstract the physical differences of the underlying hardware.  
+
+For example,the `Junos::Ez::Vlans::Provider` allows you to manage vlans without having to worry about the differences between the EX product family and the MX product family.  To you, the programmer, you simply obtain a resource and manage the associated properties.
+
+There are collection of standard facts that are always read by the framework.  You can find a list of these and the assocaited code in the *libs/../facts* subdirectory.  These facts are also avaialble to your program as well.  So you can make programmatic decisions based on the facts of the device.
+
+You can also define your own facts, and then go on to building your own provider libraries (but we're getting ahead of ourselfs here ...)
+
+# USAGE
+
+Usage rule: you **MUST** call `Junos::Ez::Provider` on your netconf object:
+
+  - **AFTER** the object has connected to the target, since it will read facts
+  - **BEFORE** you add any other providers, since these may use the facts
+  
+Here is a basic example:
+
+```ruby
+require 'pp'
+require 'net/netconf/jnpr'
+require 'junos-ez/stdlib'
+
+login = { :target => ARGV[0], :username => 'jeremy',  :password => 'jeremy1',  }
+
+# create a NETCONF object to manage the device
+
+ndev = Netconf::SSH.new( login )
+
+# open the NETCONF connetion, if this fails, the object will throw an exception
+ndev.open
+
+# now that the netconf session has been established, initialize the object for the
+# Junos::Ez framework.  This will add an instance variable called `@facts` and
+# retrieve all known facts from the target
+
+Junos::Ez::Provider( ndev )
+
+# do a quick dump of all facts
+
+pp ndev.facts.catalog
+-> 
+{:hardwaremodel=>"SRX210H",
+ :serialnumber=>"AD2909AA0096",
+ :hostname=>"srx210",
+ :domain=>"workflowsherpas.com",
+ :fqdn=>"srx210.workflowsherpas.com",
+ :RE=>
+  {:status=>"OK",
+   :model=>"RE-SRX210H",
+   :up_time=>"26 days, 15 hours, 46 minutes, 4 seconds",
+   :last_reboot_reason=>"0x200:normal shutdown"},
+ :personality=>:SRX_BRANCH,
+ :ifd_style=>:CLASSIC,
+ :switch_style=>:VLAN,
+ :version=>"12.1X44-D10.4"}
+```
+
+# STANDARD FACTS
+
+The following facts are provided by the `Junos::Ez::Provider` framework:
+```
+:hardwaremodel => String
+```
+Identifies the target hardware model as obtained from the chassis inventory information
+```
+:serialnumber => String
+```
+Identifies the target chassis serial-number as obtained from the chassis inventory information
+```
+:hostname => String
+```
+Identifies the target host-name as obtained from the system configuration
+```
+:domain => String
+```
+Identifies the target domain-name as obtained from the system configuration
+```
+:fqdn => String
+```
+Identifies the target Fully-Qualified-Domain-Name (FQDN), which is the composite of the `:hostname` and `:domain` facts.
+```
+:version => String
+```
+Identifies the Junos version string, e.g. "12.3R2.5" running on the master routing-engine.
+```
+:version_<RE | FPC + ID> => String
+```
+When the target is a multi-routing-engine or virtual-chassis system, the version loaded on each control processor is provided as a separate version fact.  All version facts begin with `version_`.  So and MX router with two routing-engines would have `:version_RE0` and `:version_RE1` in additon to the `:version` fact.  An EX vritual chassis with two members would have `:version_FPC0` and `:version_FPC1` facts in additon to the `:version` fact.
+```
+:master => String
+```
+If the target is a multi-routing-engine capabile, this fact will identify the master RE, for example "0".
+```
+:RE<SLOD_ID> => Hash
+```
+For each routing-engine, a Hash structure of information is obtained.  
+The following illustrates an EX virtual-chassis:
+```ruby
+ndev.facts.catalog
+-> 
+{:hardwaremodel=>"Virtual Chassis",
+ :serialnumber=>"BP0208207236",
+ :hostname=>"jex",
+ :domain=>"workflowsherpas.com",
+ :fqdn=>"jex.workflowsherpas.com",
+ :RE0=>
+  {:mastership_state=>"master",
+   :status=>"OK",
+   :model=>"EX4200-48T, 8 POE",
+   :up_time=>"14 minutes, 12 seconds",
+   :last_reboot_reason=>"0x2:watchdog "},
+ :master=>"0",
+ :RE1=>
+  {:mastership_state=>"backup",
+   :status=>"OK",
+   :model=>"EX4200-48T, 8 POE",
+   :up_time=>"14 minutes, 12 seconds",
+   :last_reboot_reason=>"0x2:watchdog "},
+ :personality=>:SWITCH,
+ :ifd_style=>:SWITCH,
+ :switch_style=>:VLAN,
+ :version_FPC0=>"12.2R3.5",
+ :version_FPC1=>"12.2R3.5",
+ :version_FPC2=>"12.2R3.5",
+ :version=>"12.2R3.5"}
+```
+Note the presense of`:RE0` and `:RE1` facts, each contains the Hash information for each routing-engine.  If a target does not support multiple routing-engnies, then there will be a `:RE` fact (no slot-id).
+```
+:switch_style => [:VLAN, :BRIDGE_DOMAIN, :VLAN_ELS, :NONE]
+```
+Identifies the target style for handing vlan configurations.  If the target does not support vlan briding (for example the vSRX), then the style will be set to `:NONE`.  
+```
+:personality => [:SWITCH, :MX, :SRX_BRANCH, :SRX_HIGHEND]
+```
+Identifies the personality of the target.
+```
+:ifd_style => [:CLASSIC, :SWITCH]
+```
+Identifies the target style for handling interface configuration differences.
+```
+:virtual => true
+```
+Set if the target is a virtual-machine, like the vSRX
+
+# METHODS
+  
+  - `read!` - reloads the facts from the target
+  - `facts[]` - retrieve a specific fact from the keeper
+  - `fact` - alternative method to retrieve a specific fact from the keeper
+  - `list`, `list!` - returns an Array of fact names (symbols)
+  - `catalog`, `catalog!` - returns a Hash of fact names and values
+  
+The bang (!) indicates that the method will re-read the value from the target, which the non-bang method uses the values cached in memory.  If the cache does not exist, the framework will read the values. The use of the bang-methods are handy if/when you have facts whose values change at runtime, like the `ndev.fact(:RE)[:up_time]`
+
+# CREATING CUSTOM FACTS
+
+You can define your own facts using `Junos::Ez::Facts::Keeper.define`.  You can review the stdlib facts by looking the *libs/../facts* subdirectory of this repo.  Here is the code for the `:chassis` fact.  What is interesting about this example, is this code will actually create multiple facts about the chassis.  So there is not a required one-to-one relationship between createing a custom fact and the actual number of facts it creates, yo!
+
+When you define your fact, you must give it a unique "fact name*, and a block.  The block takee two arguments: the first is the netconf object, which will provide you access to the underlying Junos XML netconf, an a Hash that allows you to write your facts into the Keeper:
+
+```ruby
+Junos::Ez::Facts::Keeper.define( :chassis ) do |ndev, facts|
+  
+  inv_info = ndev.rpc.get_chassis_inventory
+  chassis = inv_info.xpath('chassis')
+  
+  facts[:hardwaremodel] = chassis.xpath('description').text
+  facts[:serialnumber] = chassis.xpath('serial-number').text           
+  
+  cfg = ndev.rpc.get_configuration{|xml|
+    xml.system {
+      xml.send(:'host-name')
+      xml.send(:'domain-name')
+    }
+  }
+  
+  facts[:hostname] = cfg.xpath('//host-name').text
+  facts[:domain] = cfg.xpath('//domain-name').text
+  facts[:fqdn] = facts[:hostname]
+  facts[:fqdn] += ".#{facts[:domain]}" unless facts[:domain].empty?
+  
+end
+```
+
+
+
+
+
+