junos-ez-stdlib 0.0.17 → 0.1.0

data/CHANGELOG.md

@@ -21,6 +21,8 @@
   
     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
   
@@ -37,4 +39,8 @@
     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.
+  
  

data/docs/Facts.md

@@ -1,4 +1,4 @@
-# Fact Keeping
+# 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.  
@@ -9,12 +9,11 @@ There are collection of standard facts that are always read by the framework.  Y
 
 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
 
 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:
@@ -59,17 +58,104 @@ pp ndev.facts.catalog
  :version=>"12.1X44-D10.4"}
 ```
 
-# Methods
+# 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
-  - `[]` - retrieve a specific fact from the keeper
+  - `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]`
 
-# Definig Custom Facts
+# 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!
 

data/docs/Providers_Resources.md

@@ -314,7 +314,7 @@ port.write!
 
 ### Interating Resources
 
-You can use the `each` method to interate through each managed resource.  For example:
+You can use the `each` method to iterate through each managed resource, as provided by the `list` provider instance variable.  For example:
 
 ```ruby
 ndev.l1_ports.each do |port|
@@ -324,3 +324,30 @@ ndev.l1_ports.each do |port|
   end
 end
 ```
+
+You can use the `with` method to iterate through a given list of managed resources.  For example:
+
+```ruby
+# dump the status for just these two IP ports ...
+
+ip_list = ["ge-0/0/1.719","ge-0/0/1.335"]
+
+ndev.ip_ports.with(ip_list) do |ip|
+  pp ip.name
+  pp ip.status
+end
+
+->
+"ge-0/0/1.719"
+{:l1_oper_status=>:up,
+ :oper_status=>:down,
+ :snmp_index=>616,
+ :packets_rx=>0,
+ :packets_tx=>0}
+"ge-0/0/1.335"
+{:l1_oper_status=>:up,
+ :oper_status=>:up,
+ :snmp_index=>613,
+ :packets_rx=>0,
+ :packets_tx=>0}
+```

data/docs/Utils/SCP.md

@@ -0,0 +1,24 @@
+# `Net::SCP`
+
+The NETCONF object already provides a mechanism to use secure-copy (SCP), so technically this is _not_ part of the `Junos::EZ` framework.  That being said, this is some quick documentation and URLs so you can copy files to and from Junos devices.
+
+# DOCS
+
+For documentation on `Net::SCP`, please refer to this website: http://net-ssh.github.io/scp/v1/api/index.html
+
+# USAGE
+
+The NETCONF object includes an instance variable `scp` that is class `Net::SCP`.
+
+To copy a file from the server to the Junos target, you use the `upload` or `upload!` method.  The bang(!) version is blocking, meaning the code execution will resume only after the file has been completely transfered.
+
+```ruby
+file_on_server = "/cygwin/junos/junos-ex4200-image.tgz"
+location_on_junos = "/var/tmp"
+
+ndev.scp.upload!( from_on_server, location_on_junos )
+```
+
+To copy a file from the Junos target to the server, you use the `download` or `download!` method.
+
+Both upload and download methods can take a Ruby block which is used to provide progress updates on the transfer.  There is a complete "software upgrade" example that illustrates this technique in the _examples_ directory.

data/examples/re_upgrade.rb

@@ -23,7 +23,7 @@ puts "OK!"
 ## attach our private & utils that we need ...
 
 Junos::Ez::Provider( ndev )
-Junos::Ez::RE::Utils( ndev, :re )       # routine-engine utils
+Junos::Ez::RE::Utils( ndev, :re )       # routing-engine utils
 Junos::Ez::FS::Utils( ndev, :fs )       # filesystem utils
 
 ## upload the software image to the target device

data/lib/junos-ez/exceptions.rb

@@ -1,3 +1,3 @@
 module Junos::Ez
-  class NoProvider < StandardError; end
+  class NoProviderError < StandardError; end
 end

data/lib/junos-ez/facts/personality.rb

@@ -1,8 +1,11 @@
 Junos::Ez::Facts::Keeper.define( :personality ) do |ndev, facts|
   
   model = uses :hardwaremodel  
+  uses :routingengines
+
+  examine = ( model != "Virtual Chassis" ) ? model : facts[:RE0][:model]
       
-  facts[:personality] = case model   
+  facts[:personality] = case examine   
   when /^(EX)|(QFX)/
     :SWITCH
   when /^MX/

data/lib/junos-ez/provider.rb

@@ -14,7 +14,7 @@ require 'junos-ez/exceptions.rb'
   
 module Junos::Ez
   
-  VERSION = "0.0.17"
+  VERSION = "0.1.0"
   
   ### ---------------------------------------------------------------
   ### rpc_errors - decodes the XML into an array of error/Hash
@@ -361,16 +361,26 @@ class Junos::Ez::Provider::Parent
   end
   
   ### ---------------------------------------------------------------
-  ### Provider each method - this will go and create a managed 
-  ### object for each item in the list.  This could get CPU
-  ### intensive depending on the number of items under provider
-  ### management, yo!
+  ### Provider `each` - iterate through each managed resource
+  ### as obtained from the `list` instance variable.  select the
+  ### object and pass it to the provided block
   ### ---------------------------------------------------------------    
   
   def each( &block )
     raise ArgumentError, "not a provider" unless is_provider?
     list.each{ |name| yield select(name ) }
   end
+
+  ### ---------------------------------------------------------------
+  ### Provider `with` - iterate through each managed resource
+  ### as obtained from the `given_list` instance variable.  
+  ### select the object and pass it to the provided block
+  ### ---------------------------------------------------------------    
+  
+  def with( given_list, &block )
+    raise ArgumentError, "not a provider" unless is_provider?
+    given_list.each{ |name| yield select( name ) }
+  end
   
   ### ---------------------------------------------------------------
   ### Provider reader methods

data/lib/junos-ez/vlans.rb

@@ -16,7 +16,7 @@ module Junos::Ez::Vlans
     when :BRIDGE_DOMAIN
       Junos::Ez::Vlans::Provider::BRIDGE_DOMAIN.new( ndev )     
     else
-      raise Junos::Ez::NoProvider, "target does not support vlan bridges"
+      raise Junos::Ez::NoProviderError, "target does not support vlan bridges"
     end      
     newbie.properties = Junos::Ez::Provider::PROPERTIES + PROPERTIES
     Junos::Ez::Provider.attach_instance_variable( ndev, varsym, newbie )

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: junos-ez-stdlib
 version: !ruby/object:Gem::Version
-  version: 0.0.17
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-05 00:00:00.000000000 Z
+date: 2013-05-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: netconf
@@ -92,6 +92,7 @@ files:
 - docs/Utils/Config.md
 - docs/Utils/Filesystem.md
 - docs/Utils/Routing-Engine.md
+- docs/Utils/SCP.md
 homepage: https://github.com/jeremyschulman/ruby-junos-ez-stdlib
 licenses: []
 post_install_message: