junos-ez-stdlib 0.0.12 → 0.0.15

data/docs/Utils/Filesystem.md

@@ -0,0 +1,78 @@
+# Filesystem Utilities
+
+A collection of methods to access filesystem specific functions and information. These methods return data in 
+Hash / Array structures so the information can be programmatically accessible, rather than scraping CLI or navigating
+Junos XML.
+
+# USAGE
+```ruby
+
+# bind :fs to access the file-system utilities
+
+Junos::Ez::FS::Utils( ndev, :fs )
+
+# get a listing of my home directory files:
+
+pp ndev.fs.ls '/var/home/jeremy', :detail => true
+->
+{"/var/home/jeremy"=>
+  {:fileblocks=>11244,
+   :files=>
+     "key1.pub"=>
+      {:owner=>"jeremy",
+       :group=>"staff",
+       :links=>1,
+       :size=>405,
+       :permissions_text=>"-rw-r--r--",
+       :permissions=>644,
+       :date=>"Apr 27 15:00",
+       :date_epoc=>1367074832}, 
+     "template-policy-options.conf"=>
+      {:owner=>"jeremy",
+       :group=>"staff",
+       :links=>1,
+       :size=>4320,
+       :permissions_text=>"-rw-r--r--",
+       :permissions=>644,
+       :date=>"Nov 6   2011",
+       :date_epoc=>1320564278}},
+   :dirs=>
+    {".ssh"=>
+      {:owner=>"jeremy",
+       :group=>"staff",
+       :links=>2,
+       :size=>512,
+       :permissions_text=>"drwxr-xr-x",
+       :permissions=>755,
+       :date=>"Apr 27 19:48",
+       :date_epoc=>1367092112},
+     "bak"=>
+      {:owner=>"jeremy",
+       :group=>"staff",
+       :links=>2,
+       :size=>512,
+       :permissions_text=>"drwxr-xr-x",
+       :permissions=>755,
+       :date=>"Apr 16  2010",
+       :date_epoc=>1271441068}}}}
+```
+
+# METHODS
+
+  - `cat` - returns the String contents of a file
+  - `checksum` - returns the checksum of a file (MD5, SHA1, SHA256 options)
+  - `cleanup?` - returns a Hash of files that *would be* removed from "request system storage cleanup"
+  - `cleanup!` - "request system storage cleanup" (!! NO CONFIRM !!)
+  - `cp!` - copies a file relative on the device filesystem
+  - `cwd` - changes the current working directory
+  - `pwd` - returns a String of the current working directory
+  - `df` - "show system storage"
+  - `ls` - "file list", i.e. get a file / directory listing, returns a Hash
+  - `mv!` - "file move", i.e. move / rename files
+  - `rm!` - "file delete", i.e. deletes files
+
+# GORY DETAILS
+
+... more docs comming ...
+
+

data/docs/Utils/Routing-Engine.md

@@ -0,0 +1,248 @@
+# Junos::Ez::RE::Utils
+
+A collection of methods to access routing-engine specific functions and information.  These methods return data in Hash / Array structures so the information can be programmatically accessible, rather than scraping CLI or navigating Junos XML.
+
+# USAGE
+
+```ruby
+
+# bind :re to access the routing-engine utitities
+Junos::Ez::RE::Utils( ndev, :re )
+
+# show the uptime information on this device
+pp ndev.re.uptime
+->
+{"re0"=>
+  {:time_now=>"2013-04-27 22:28:24 UTC",
+   :active_users=>1,
+   :load_avg=>[0.08, 0.05, 0.01],
+   :uptime=>{:at=>"10:28PM", :ago=>"27 days,  2:58"},
+   :time_boot=>{:at=>"2013-03-31 19:30:47 UTC", :ago=>"3w6d 02:57"},
+   :protocols_started=>{:at=>"2013-03-31 19:34:53 UTC", :ago=>"3w6d 02:53"},
+   :last_config=>
+    {:at=>"2013-04-27 19:48:42 UTC", :ago=>"02:39:42", :by=>"jeremy"}}}
+```
+
+# METHODS
+
+## Information
+
+  - `status` - "show chassis routing-engine" information
+  - `uptime` - "show system uptime" information
+  - `system_alarms` - "show system alarms" information
+  - `chassis_alarms` - "show chassis alarms" information
+  - `memory` - "show system memory" information
+  - `users` - "show system users" information
+
+## Software Image
+
+  - `validate_software?` - "request system software validate..."
+  - `install_software!` - "request system software add ..."
+  - `rollback_software!` - "request system software rollback"
+
+## System Controls
+
+  - `reboot!` - "request system reboot" (!! NO CONFIRM !!)
+  - `shutdown!` - "request system power-off" (!! NO CONFIRM !!)
+
+# GORY DETAILS
+
+## status
+
+Returns a Hash structure of "show chassis routing-engine" information.  Each Hash key is the RE identifier.  For example, on a target with a single RE:
+```ruby
+pp ndev.re.status
+->
+{"re0"=>
+  {:model=>"JUNOSV-FIREFLY RE",
+   :serialnumber=>"",
+   :temperature=>{:system=>"", :cpu=>""},
+   :memory=>{:total_size=>0, :buffer_util=>0},
+   :cpu_util=>{:user=>0, :background=>0, :system=>2, :interrupt=>0, :idle=>98},
+   :uptime=>
+    {:at=>"2013-05-02 17:37:51 UTC",
+     :ago=>"3 minutes, 4 seconds",
+     :reboot_reason=>"Router rebooted after a normal shutdown."},
+   :load_avg=>[0.06, 0.13, 0.07]}}
+```
+
+## uptime
+
+Returns a Hash structure of "show system uptime" information.  Each Hash key is the RE identifier.  For example, on a target with a single RE:
+```ruby
+pp ndev.re.uptime
+->
+{"re0"=>
+  {:time_now=>"2013-05-02 17:42:09 UTC",
+   :active_users=>0,
+   :load_avg=>[0.02, 0.1, 0.06],
+   :uptime=>{:at=>"5:42PM", :ago=>"4 mins"},
+   :time_boot=>{:at=>"2013-05-02 17:37:51 UTC", :ago=>"00:04:18"},
+   :protocols_started=>{:at=>"2013-05-02 17:38:08 UTC", :ago=>"00:04:01"},
+   :last_config=>
+    {:at=>"2013-04-27 15:00:55 UTC", :ago=>"5d 02:41", :by=>"root"}}}
+```
+## system_alarms
+
+Returns an Array of Hash structure of "show system alarms" information.  If there are no alarms, this method returns `nil`.  For example, a target with a single alarm:
+```ruby
+pp ndev.re.system_alarms
+-> 
+[{:at=>"2013-05-02 17:38:03 UTC",
+  :class=>"Minor",
+  :description=>"Rescue configuration is not set",
+  :type=>"Configuration"}]
+```
+
+## chassis_alarms
+
+Returns an Array Hash structure of "show chassis alarms" information.  If there are no alarms, this method returns `nil`.  For example, a target with no chassis alarms:
+```ruby
+pp ndev.re.chassis_alarms
+->
+nil
+```
+
+## memory
+
+Returns a Hash structure of "show system memory" information.  Each key is the RE indentifier.  A target with a single RE would look like the following.  Note that the `:procs` Array is the process array, with each element as a Hash of process specific information.
+```ruby
+pp ndev.re.memory
+-> 
+{"re0"=>
+  {:memory_summary=>
+    {:total=>{:size=>1035668, :percentage=>100},
+     :reserved=>{:size=>18688, :percentage=>1},
+     :wired=>{:size=>492936, :percentage=>47},
+     :active=>{:size=>184152, :percentage=>17},
+     :inactive=>{:size=>65192, :percentage=>6},
+     :cache=>{:size=>261140, :percentage=>25},
+     :free=>{:size=>12660, :percentage=>1}},
+   :procs=>
+    [{:name=>"kernel",
+      :pid=>0,
+      :size=>569704,
+      :size_pct=>54.49,
+      :resident=>90304,
+      :resident_pct=>8.71},
+     {:name=>"/sbin/pmap",
+      :pid=>2768,
+      :size=>4764,
+      :size_pct=>0.15,
+      :resident=>1000,
+      :resident_pct=>0.09},
+     {:name=>"file: (mgd) /proc/2766/file (jeremy)",
+      :pid=>2765,
+      :size=>727896,
+      :size_pct=>23.16,
+      :resident=>18904,
+      :resident_pct=>1.82},
+      #
+      # snip, omitted full array for sake of sanity ...
+      #
+    ]}}
+```
+
+## users 
+
+Returns a Array structure of "show system users" information.  Each Array item is a Hash structure of user information.  A target with a single user logged in would look like:
+```ruby
+pp ndev.re.users
+-> 
+[{:name=>"jeremy",
+  :tty=>"p0",
+  :from=>"192.168.56.1",
+  :login_time=>"5:45PM",
+  :idle_time=>"",
+  :command=>"-cli (cli)"}]
+```
+
+## validate_software?
+
+Performs the equivalent of "request system software validate..." and returns `true` if the software passes validation or a String indicating the error message.  The following is an example that simply checks for true:
+```ruby
+unless ndev.re.validate_software?( file_on_junos )
+  puts "The softare does not validate!"
+  ndev.close
+  exit 1
+end
+```
+
+## install_software! 
+
+Performs the equivalent of "request system software add ..." and returns `true` if the operation was successful or a String indicating the error message.  The following example illustrates an error message:
+
+```ruby
+puts "Installing image ... please wait ..."
+rc = ndev.re.install_software!( :package => file_on_junos, :no_validate => true )
+if rc != true
+  puts rc
+end
+```
+With the results of the `rc` String:
+```
+Verified junos-boot-vsrx-12.1I20130415_junos_121_x44_d15.0-576602.tgz signed by PackageDevelopment_12_1_0
+Verified junos-vsrx-12.1I20130415_junos_121_x44_d15.0-576602-domestic signed by PackageDevelopment_12_1_0
+
+WARNING:     The software that is being installed has limited support.
+WARNING:     Run 'file show /etc/notices/unsupported.txt' for details.
+
+Available space: -49868 require: 4641
+
+WARNING: The /cf filesystem is low on free disk space.
+WARNING: This package requires 4641k free, but there
+WARNING: is only -49868k available.
+
+WARNING: This installation attempt will be aborted.
+WARNING: If you wish to force the installation despite these warnings
+WARNING: you may use the 'force' option on the command line.
+ERROR: junos-12.1I20130415_junos_121_x44_d15.0-576602-domestic fails requirements check
+Installation failed for package '/var/tmp/junos-vsrx-domestic.tgz'
+WARNING: Not enough space in /var/tmp to unpack junos-12.1I20130415_junos_121_x44_d15.0-576602.tgz
+WARNING: Use 'request system storage cleanup' and
+WARNING: the 'unlink' option to improve the chances of success
+```
+
+## rollback_software!
+
+Performs the equivalent of "request system software rollback".  The result of the operation is returned as a String.  For example, a successful rollback would look like this:
+```ruby
+pp ndev.re.rollback_software!
+-> 
+"Restoring boot file package\njunos-12.1I20130422_2129_jni-domestic will become active at next reboot\nWARNING: A reboot is required to load this software correctly\nWARNING:     Use the 'request system reboot' command\nWARNING:         when software installation is complete"
+```
+An unsuccessful rollback would look like this:
+```ruby
+pp ndev.re.rollback_software!
+-> 
+"WARNING: Cannot rollback, /packages/junos is not valid"
+```
+
+## reboot!( opts = {} )
+
+Performs the "request system reboot" action.  There is **NO** confirmation prompt, so once you've executed this method, the action begins.  Once this command executes the NETCONF session to the target will eventually terminate.  You can trap the `Net::SSH::Disconnect` exception to detect this event.
+
+The option Hash provides for the following controls:
+```
+:in => Fixnum
+```
+Instructs Junos to reboot after `:in` minutes from the time of calling `reboot!`
+```
+:at => String
+```
+Instructs Junos to reboot at a specific date and time.  The format of `:at` is YYYYMMDDHHMM, where HH is the 24-hour (military) time.  For example HH = 01 is 1am and HH=13 is 1pm.  If you omit the YYYY, MM, or DD options the current values apply.  For example `:at => 1730` is 1:30pm today.
+
+## shutdown!( opts = {} )
+
+Performs the "request system power-off" action.  There is **NO** confirmation prompt, so once you've executed this method, the action begins.  Once this command executes the NETCONF session to the target will eventually terminate.  You can trap the `Net::SSH::Disconnect` exception to detect this event.
+
+The option Hash provides for the following controls:
+```
+:in => Fixnum
+```
+Instructs Junos to reboot after `:in` minutes from the time of calling `reboot!`
+```
+:at => String
+```
+Instructs Junos to reboot at a specific date and time.  The format of `:at` is YYYYMMDDHHMM, where HH is the 24-hour (military) time.  For example HH = 01 is 1am and HH=13 is 1pm.  If you omit the YYYY, MM, or DD options the current values apply.  For example `:at => 1730` is 1:30pm today.
+

data/examples/re_upgrade.rb

@@ -73,7 +73,7 @@ unless ndev.re.validate_software?( file_on_junos )
   exit 1
 end
 
-puts "Installing image ... place wait ..."
+puts "Installing image ... please wait ..."
 rc = ndev.re.install_software!( :package => file_on_junos, :no_validate => true )
 if rc != true
   puts rc

data/examples/re_utils.rb

@@ -24,6 +24,7 @@ puts "OK!"
 Junos::Ez::Provider( ndev )
 Junos::Ez::RE::Utils( ndev, :re )
 Junos::Ez::FS::Utils( ndev, :fs )
+Junos::Ez::Config::Utils( ndev, :cu )
 
 binding.pry
 

data/examples/vlans.rb

@@ -1,8 +1,12 @@
 require 'net/netconf/jnpr'
 require 'junos-ez/stdlib'
 
-# login information for NETCONF session 
+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 ...
@@ -15,7 +19,9 @@ $stdout.puts "OK!"
 Junos::Ez::Provider( ndev )
 Junos::Ez::Config::Utils( ndev, :cu )
 Junos::Ez::Vlans::Provider( ndev, :vlans )
+Junos::Ez::L1ports::Provider( ndev, :l1_ports )
 Junos::Ez::L2ports::Provider( ndev, :l2_ports )
+Junos::Ez::IPports::Provider( ndev, :ip_ports )
 
 pp ndev.vlans.list
 pp ndev.vlans.catalog

data/lib/junos-ez/ip_ports.rb

@@ -8,7 +8,9 @@ module Junos::Ez::IPports
     :description,       # general description text
     :tag_id,            # VLAN tag-id for vlan-tag enabled ports
     :mtu,               # MTU value as number
-    :address            # ip/prefix as text, e.g. "192.168.10.22/24"
+    :address,           # ip/prefix as text, e.g. "192.168.10.22/24"
+    :acl_in,            # input ACL name
+    :acl_out,           # output ACL name
   ]  
 
   def self.Provider( ndev, varsym )            

data/lib/junos-ez/ip_ports/classic.rb

@@ -7,13 +7,13 @@ class Junos::Ez::IPports::Provider::CLASSIC < Junos::Ez::IPports::Provider
   def xml_at_top    
     
     # if just the IFD is given as the name, default to unit "0"
-    @ifd, @ifl = @name.split '.'
-    @ifl ||= "0"
+    @ifd, @ifd_unit = @name.split '.'
+    @ifd_unit ||= "0"
     
     Nokogiri::XML::Builder.new{ |x| x.configuration{ 
       x.interfaces { x.interface { x.name @ifd
         x.unit {
-          x.name @ifl
+          x.name @ifd_unit
           return x
         }
       }}
@@ -43,14 +43,22 @@ class Junos::Ez::IPports::Provider::CLASSIC < Junos::Ez::IPports::Provider
     
   def xml_read_parser( as_xml, as_hash )
     set_has_status( as_xml, as_hash )    
-    
+
+    as_hash[:admin] = as_xml.xpath('disable').empty? ? :up : :down    
     ifa_inet = as_xml.xpath('family/inet')
     
-    as_hash[:tag_id] = as_xml.xpath('vlan-id').text.to_i
-    as_hash[:description] = as_xml.xpath('description').text
-    as_hash[:mtu] = ifa_inet.xpath('mtu').text.to_i || nil
+    xml_when_item(as_xml.xpath('vlan-id')){ |i| as_hash[:tag_id] = i.text.to_i }
+    xml_when_item(as_xml.xpath('description')){ |i| as_hash[:description] = i.text }
+    xml_when_item(ifa_inet.xpath('mtu')){ |i| as_hash[:mtu] = i.text.to_i }   
+    
+    # @@@ assuming a single IP address; prolly need to be more specific ...
     as_hash[:address] = ifa_inet.xpath('address/name').text || nil
-    as_hash[:admin] = as_xml.xpath('disable').empty? ? :up : :down
+    
+    # check for firewall-filters (aka ACLs)
+    if (fw_acl = ifa_inet.xpath('filter')[0])
+      xml_when_item( fw_acl.xpath('input/filter-name')){ |i| as_hash[:acl_in] = i.text.strip }
+      xml_when_item( fw_acl.xpath('output/filter-name')){ |i| as_hash[:acl_out] = i.text.strip }
+    end
     
     return true
   end  
@@ -61,14 +69,11 @@ class Junos::Ez::IPports::Provider::CLASSIC < Junos::Ez::IPports::Provider
   
   def xml_change_address( xml )
     xml.family { xml.inet {
+      # delete the old address and replace it with the new one ...
       if @has[:address]
-        xml.address( Netconf::JunosConfig::DELETE ) {
-          xml.name @has[:address]
-        }
+        xml.address( Netconf::JunosConfig::DELETE ) { xml.name @has[:address] }
       end
-      xml.address { 
-        xml.name @should[:address] 
-      }
+      xml.address { xml.name @should[:address] }
     }}
   end
   
@@ -81,9 +86,39 @@ class Junos::Ez::IPports::Provider::CLASSIC < Junos::Ez::IPports::Provider
       xml_set_or_delete( xml, 'mtu', @should[:mtu] )
     }}
   end   
+  
+  def xml_change_acl_in( xml )
+    xml.family { xml.inet { xml.filter { xml.input {
+      xml_set_or_delete( xml, 'filter-name', @should[:acl_in] )
+    }}}}
+  end
+  
+  def xml_change_acl_out( xml )
+    xml.family { xml.inet { xml.filter { xml.output {
+      xml_set_or_delete( xml, 'filter-name', @should[:acl_out] )      
+    }}}}    
+  end
 
 end
 
+##### ---------------------------------------------------------------
+##### Resource Methods
+##### ---------------------------------------------------------------
+
+class Junos::Ez::IPports::Provider::CLASSIC
+  def status
+    got = @ndev.rpc.get_interface_information( :interface_name => @ifd+'.'+@ifd_unit )
+    ifs = got.xpath('logical-interface')[0]  
+    ret_h = {}
+    ret_h[:l1_oper_status] = (ifs.xpath('if-config-flags/iff-device-down')[0]) ? :down : :up
+    ret_h[:oper_status] = (ifs.xpath('address-family//ifaf-down')[0]) ? :down : :up    
+    ret_h[:snmp_index] = ifs.xpath('snmp-index').text.to_i
+    ret_h[:packets_rx] = ifs.xpath('traffic-statistics/input-packets').text.to_i
+    ret_h[:packets_tx] = ifs.xpath('traffic-statistics/output-packets').text.to_i
+    ret_h
+  end
+end
+
 ##### ---------------------------------------------------------------
 ##### Provider collection methods
 ##### ---------------------------------------------------------------