junos-ez-stdlib 0.0.15 → 0.0.16

data/CHANGELOG.md

@@ -31,3 +31,10 @@
     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.
+  
+ 

data/docs/Facts.md

@@ -46,8 +46,8 @@ pp ndev.facts.catalog
 {:hardwaremodel=>"SRX210H",
  :serialnumber=>"AD2909AA0096",
  :hostname=>"srx210",
- :domain=>"",
- :fqdn=>"srx210",
+ :domain=>"workflowsherpas.com",
+ :fqdn=>"srx210.workflowsherpas.com",
  :RE=>
   {:status=>"OK",
    :model=>"RE-SRX210H",

data/docs/Utils/Routing-Engine.md

@@ -1,4 +1,4 @@
-# Junos::Ez::RE::Utils
+# `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.
 
@@ -25,29 +25,40 @@ pp ndev.re.uptime
 
 # METHODS
 
-## Information
+## Informational
 
-  - `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
+  - [`status`](#status) - "show chassis routing-engine" information
+  - [`uptime`](#uptime) - "show system uptime" information
+  - [`system_alarms`](#system_alarms) - "show system alarms" information
+  - [`chassis_alarms`](#chassis_alarms) - "show chassis alarms" information
+  - [`memory`](#memory) - "show system memory" information
+  - [`users`](#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"
+  - [`software_validate?`](#software_validate) - "request system software validate..."
+  - [`software_install!`](#software_install) - "request system software add ..."
+  - [`software_rollback!`](#software_rollback) - "request system software rollback"
+  - [`software_images`](#software_images) - indicates current/rollback image file names
+
+## License Management
+
+  - [`license_install!`](#license_install) - "request system license add"
+  - [`license_rm!`](#license_rm) - "request system license delete"
+  - [`licenses`](#licenses) - "show system license"
 
 ## System Controls
 
-  - `reboot!` - "request system reboot" (!! NO CONFIRM !!)
-  - `shutdown!` - "request system power-off" (!! NO CONFIRM !!)
+  - [`reboot!`](#reboot) - "request system reboot" (!! NO CONFIRM !!)
+  - [`shutdown!`](#shutdown) - "request system power-off" (!! NO CONFIRM !!)
+
+## Miscellaneous
+
+  - [`ping`](#ping) - Perform a "ping" command
 
 # GORY DETAILS
 
-## status
+## `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
@@ -66,7 +77,7 @@ pp ndev.re.status
    :load_avg=>[0.06, 0.13, 0.07]}}
 ```
 
-## uptime
+## `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
@@ -82,7 +93,7 @@ pp ndev.re.uptime
    :last_config=>
     {:at=>"2013-04-27 15:00:55 UTC", :ago=>"5d 02:41", :by=>"root"}}}
 ```
-## system_alarms
+## `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
@@ -94,7 +105,7 @@ pp ndev.re.system_alarms
   :type=>"Configuration"}]
 ```
 
-## chassis_alarms
+## `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
@@ -103,7 +114,7 @@ pp ndev.re.chassis_alarms
 nil
 ```
 
-## memory
+## `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
@@ -143,7 +154,7 @@ pp ndev.re.memory
     ]}}
 ```
 
-## users 
+## `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
@@ -157,24 +168,49 @@ pp ndev.re.users
   :command=>"-cli (cli)"}]
 ```
 
-## validate_software?
+## `software_images`
+Returns a Hash of the currnet and rollback image file-names.
+```ruby
+pp ndev.re.software_images
+-> 
+{:rollback=>"junos-12.1I20130415_junos_121_x44_d15.0-576602-domestic",
+ :current=>"junos-12.1I20130322_2104_slt-builder-domestic"}
+```
+
+## `software_validate?` <a name="software_validate">
 
 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 )
+unless ndev.re.software_validate?( file_on_junos )
   puts "The softare does not validate!"
   ndev.close
   exit 1
 end
 ```
 
-## install_software! 
+## `software_install!( opts = {} )` <a name="software_install">
 
-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:
+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 options are supported:
+```
+:no_validate => true
+```
+Instructs Junos not to validate the software image.  You should use this option if your program explicity calls `software_validate?` first, since you don't want to do the validation twice.
+```
+:unlink => true
+```
+Instructs Junos to remove the software package file (.tgz) after the installation has completed. 
+```
+:reboot => true
+```
+Instructs Junos to reboot the RE after the software has been installed successfully.
+
+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 )
+rc = ndev.re.software_install!( :package => file_on_junos, :no_validate => true )
 if rc != true
   puts rc
 end
@@ -203,23 +239,22 @@ WARNING: Use 'request system storage cleanup' and
 WARNING: the 'unlink' option to improve the chances of success
 ```
 
-## rollback_software!
+## `software_rollback!` <a name="software_rollback">
 
 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!
+pp ndev.re.software_rollback!
 -> 
-"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"
+"Restoring boot file package\njunos-12.1I20130415_junos_121_x44_d15.0-576602-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!
+pp ndev.re.software_rollback!
 -> 
 "WARNING: Cannot rollback, /packages/junos is not valid"
 ```
 
-## reboot!( opts = {} )
-
+## `reboot!( opts = {} )` <a name="reboot">
 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:
@@ -232,7 +267,7 @@ Instructs Junos to reboot after `:in` minutes from the time of calling `reboot!`
 ```
 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 = {} )
+## `shutdown!( opts = {} )` <a name="shutdown">
 
 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.
 
@@ -246,3 +281,98 @@ Instructs Junos to reboot after `:in` minutes from the time of calling `reboot!`
 ```
 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.
 
+## `license_install!( opts = {} )` <a name="license_install">
+Installs the provided license.  This method will return `true` if the key is installed correctly or a String message indicating the error.
+
+The following options are supported, you **MUST** use either `:key` or `:filename` to provide the license ASCII-text.
+```
+:key
+```
+The ASCII-text of the key.
+```
+:filename
+```
+The path to the file on the server (not Junos) that contains the ASCII-text of the key.
+
+The following illustates how to load a key from the server filesystem.
+```ruby
+ndev.re.license_install! :filename=>'/cygwin/home/jschulman/license.txt'
+->
+true
+```
+## `license_rm!( license_id )` <a name="license_rm">
+Removes either a specific license or `:all` licenses from the target.  This method will return `true` if the action was successful, or a String error-message otherwise.
+
+Removing a specific license:
+```ruby
+ndev.re.license_rm! "JUNOS410496"
+->
+true
+```
+Removing all licenses
+```ruby
+ndev.re.license_rm! :all
+->
+true
+```
+
+## `licenses( opts = {} )` <a name="licenses">
+
+Returns a Hash structure of information gathered from the "show system license" command.
+
+The following options are supported:
+```
+:keys => true
+```
+Returns the license key value in ASCII text format.
+
+Without the `:keys` option:
+
+```ruby
+pp ndev.re.licenses
+-> 
+{"JUNOS410496"=>
+  {:state=>"valid",
+   :version=>"2",
+   :serialnumber=>"91730A00092074",
+   :customer=>"LABVSRXJuniper-SEs",
+   :features=>
+    {"all"=>
+      {:description=>"All features",
+       :date_start=>"2013-02-05",
+       :date_end=>"2014-02-06"}}}}
+```
+With the `:keys` option:
+```ruby
+pp ndev.re.licenses :keys=>true
+-> 
+{"JUNOS410496"=>
+  {:state=>"valid",
+   :version=>"2",
+   :serialnumber=>"91730A00092074",
+   :customer=>"LABVSRXJuniper-SEs",
+   :features=>
+    {"all"=>
+      {:description=>"All features",
+       :date_start=>"2013-02-05",
+       :date_end=>"2014-02-06"}},
+   :key=>
+    "\nJUNOS410496 aeaqec agaia3 27n65m fq4ojr g4ztaq jqgayd\n            smrqg4 2aye2m ifbfmu DEADBEF k3tjob sxelkt\n  <snip>"}}
+```
+
+## `ping( host, opts = {} )` <a name="ping">
+
+Issues a 'ping' from the Junos target, very handy for troubleshooting.  This method will return `true` if the ping action was successful, or `false` otherwise.
+
+The following options are supported, and they are the same as documented by the Junos techpubs:
+```
+      :do_not_fragment, :inet, :inet6, :strict,      
+      :count, :interface, :interval, :mac_address,
+      :routing_instance, :size, :source, :tos, :ttl, :wait
+```
+Here is a ping example that uses the 'do-no-fragment' and 'count' options:
+```ruby
+ndev.re.ping "192.168.56.1", :count => 5, :do_not_fragment => true
+->
+true
+```

data/examples/re_upgrade.rb

@@ -38,23 +38,27 @@ file_on_junos = '/var/tmp/' + file_name
 
 def copy_file_to_junos( ndev, file_on_server, file_on_junos )  
   mgr_i = cur_i = 0
+  backitup = 8.chr * 4
   ndev.scp.upload!( file_on_server, file_on_junos ) do |ch, name, sent, total|  
     pct = (sent.to_f / total.to_f) * 100
     mgr_i = pct.to_i
     if mgr_i != cur_i
       cur_i = mgr_i
-      puts cur_i.to_s + "%"
+      printf "%4s", cur_i.to_s + "%"
+      print backitup
     end    
   end
 end
 
-puts "Copying file to Junos ..."
+print "Copying file to Junos ... "
 copy_file_to_junos( ndev, file_on_server, file_on_junos )
+puts "OK!    "
 
 ###
 ### check the MD5 checksum values
 ###
 
+print "Validating MD5 checksum ... "
 md5_on_s = Digest::MD5.file( file_on_server ).to_s
 md5_on_j = ndev.fs.checksum( :md5, file_on_junos )
 
@@ -64,27 +68,32 @@ if md5_on_s != md5_on_j
   exit 1
 end
 
-puts "MD5 checksum matches ... proceeding ..."
-puts "Validating image ... please wait ..."
+puts "OK!"
+
+print "Validating image ... please wait ... "
 
-unless ndev.re.validate_software?( file_on_junos )
+unless ndev.re.software_validate?( file_on_junos )
   puts "The softare does not validate!"
   ndev.close
   exit 1
 end
 
-puts "Installing image ... please wait ..."
-rc = ndev.re.install_software!( :package => file_on_junos, :no_validate => true )
+puts "OK!"
+
+print "Installing image ... please wait ... "
+rc = ndev.re.software_install!( :package => file_on_junos, :no_validate => true )
 if rc != true
   puts rc
 end
 
+puts "OK!"
+
 ### use pry if you want to 'look around'
 ## -> binding.pry
 
-### if you wanted to reboot the system now, you coud
-### do the following ...
-
-## -> ndev.re.reboot!
+if ARGV[1] == 'reboot'
+  puts "Rebooting!"
+  ndev.re.reboot!
+end
 
 ndev.close

data/lib/junos-ez/provider.rb

@@ -11,7 +11,7 @@ module Junos; end
   
 module Junos::Ez
   
-  VERSION = "0.0.15"
+  VERSION = "0.0.16"
   
   ### ---------------------------------------------------------------
   ### rpc_errors - decodes the XML into an array of error/Hash

data/lib/junos-ez/utils/re.rb

@@ -6,15 +6,23 @@ a misc. collection of methods that perform basic automation tasks
 like upgrading software or getting process information.  The 
 following lists the methods and the equivalent Junos CLI commands
 
-- status: show chassis routing-engine
-- uptime: show system uptime
-- system_alarms: show system alarms
-- chassis_alarms: show chassis alarms
-- memory: show system memeory
-- users: show system users
-- validate_software?: request system software validate
-- install_software!: request system software add 
-- rollback_software!: request system software rollback
+- status            show chassis routing-engine
+- uptime            show system uptime
+- system_alarms     show system alarms
+- chassis_alarms    show chassis alarms
+- memory            show system memeory
+- users             show system users
+
+- software_install!     request system software add 
+- software_rollback!    request system software rollback
+- software_validate?    request system software validate
+- software_images       - provides image file names for current/rollback
+
+- license_install!      request system license add          !! TBD !!
+- license_rm!           request system license delete
+- license_save          request system license save         !! TBD !!
+- licenses              show system license
+
 - reboot!: request system reboot (no confirm!!)
 - shutdown!: request system power-off (no confirm!!)
   
@@ -179,11 +187,17 @@ class Junos::Ez::RE::Provider < Junos::Ez::Provider::Parent
     users_a
   end
 
+  ### ===============================================================
+  ###
+  ###                   Software related methods
+  ###
+  ### ===============================================================
+  
   ### ---------------------------------------------------------------
-  ### validate_software? - request system software validate ...
+  ### software_validate? - request system software validate ...
   ### ---------------------------------------------------------------
   
-  def validate_software?( package )
+  def software_validate?( package )
     got = @ndev.rpc.request_package_validate(:package_name => package).parent
     errcode = got.xpath('package-result').text.to_i
     return true if errcode == 0
@@ -193,15 +207,16 @@ class Junos::Ez::RE::Provider < Junos::Ez::Provider::Parent
   end
 
   ### ---------------------------------------------------------------
-  ### install_software! - request system software add ...
+  ### software_install! - request system software add ...
   ### ---------------------------------------------------------------
   
-  def install_software!( opts = {} )
+  def software_install!( opts = {} )
     raise ArgumentError "missing :package" unless opts[:package]
     
     args = { :package_name => opts[:package] }
     args[:no_validate] = true if opts[:no_validate]
     args[:unlink] = true if opts[:unlink]
+    args[:reboot] = true if opts[:reboot]
     
     got = @ndev.rpc.request_package_add( args ).parent
     errcode = got.xpath('package-result').text.to_i
@@ -212,14 +227,37 @@ class Junos::Ez::RE::Provider < Junos::Ez::Provider::Parent
   end
 
   ### ---------------------------------------------------------------
-  ### rollback_software! - request system software rollback
+  ### software_rollback! - request system software rollback
   ### ---------------------------------------------------------------
   
-  def rollback_software!
+  def software_rollback!
     got = @ndev.rpc.request_package_rollback
     got.text.strip
   end
+  
+  def software_images
+    ls_pkgs = @ndev.rpc.file_list(:path=>'/packages')
+    symlink = ls_pkgs.xpath('//file-symlink-target')[0]
+    if symlink
+      ls_pkgs = @ndev.rpc.file_list(:path => symlink.text.strip)
+    end
+    
+    junos_symlink = ls_pkgs.xpath('//file-information[normalize-space(file-name) = "junos"]')[0]
+    junos_old_symlink = ls_pkgs.xpath('//file-information[normalize-space(file-name) = "junos.old"]')[0]
+    
+    ret_h = {}    
+    ret_h[:rollback] = (junos_old_symlink) ? junos_old_symlink.xpath('file-symlink-target').text.strip : nil
+    ret_h[:current] = (junos_symlink) ? junos_symlink.xpath('file-symlink-target').text.strip : ret_h[:rollback]
+    
+    ret_h
+  end
 
+  ### ===============================================================
+  ###
+  ###             Misc Routing Engine Commands & Controls
+  ###
+  ### ===============================================================
+  
   ### ---------------------------------------------------------------
   ### reboot! - request system reboot (no confirm!!)
   ### ---------------------------------------------------------------
@@ -263,15 +301,14 @@ class Junos::Ez::RE::Provider < Junos::Ez::Provider::Parent
     got.xpath('//request-reboot-status').text.strip
   end
   
-  def ping( opts = {} )
+  def ping( host, opts = {} )
     arg_options = [ 
-      :host,
       :do_not_fragment, :inet, :inet6, :strict,      
       :count, :interface, :interval, :mac_address,
       :routing_instance, :size, :source, :tos, :ttl, :wait
     ]
     
-    args = {}
+    args = {:host => host}
     opts.each do |k,v|
       if arg_options.include? k
         args[k] = v
@@ -290,6 +327,132 @@ class Junos::Ez::RE::Provider < Junos::Ez::Provider::Parent
     
     return (block_given?) ? yield(got) : false
   end
+  
+  ### ===============================================================
+  ###
+  ###                   License related methods
+  ###
+  ### ===============================================================
+  
+  ## ----------------------------------------------------------------
+  ## - retrieve Hash of license information.  
+  ##
+  ## By default this will provide the license installed
+  ## information.  
+  ## 
+  ## --- returns ---
+  ## - Hash of data if there are licenses
+  ## - nil if no licenses
+  ##
+  ## --- options ---
+  ## :keys => true
+  ##    Will include the key-text for the license
+  ##
+  ## ----------------------------------------------------------------
+  
+  def licenses( opts = {} )
+    
+    got = @ndev.rpc.get_license_summary_information
+    licenses = got.xpath('license-information/license')
+    return nil if licenses.empty?
+    
+    ret_h = {}
+    licenses.each do |lic|
+      lic_h = {}
+      ret_h[lic.xpath('name').text.strip] = lic_h
+      
+      lic_h[:state] = lic.xpath('license-state').text.strip
+      lic_h[:version] = lic.xpath('license-version').text.strip
+      lic_h[:serialnumber] = lic.xpath('software-sn').text.strip
+      lic_h[:customer] = lic.xpath('customer-reference').text.strip
+      
+      features = lic.xpath('feature-block/feature')
+      unless features.empty?
+        feats_h = {}
+        lic_h[:features] = feats_h
+        features.each do |feat|
+          feat_h = {}
+          feats_h[feat.xpath('name').text.strip] = feat_h
+          feat_h[:description] = feat.xpath('description').text.strip
+          v_info = feat.xpath('validity-information')[0]
+          case v_info.xpath('validity-type').text.strip
+          when 'date-based'
+            feat_h[:date_start] = v_info.xpath('start-date').text.strip
+            feat_h[:date_end] = v_info.xpath('end-date').text.strip
+          end
+        end # each features
+      end # if features
+    end # each license
+    
+    ## now check to see if the :keys have been requested.  if so
+    ## then get that data, and store back into the return Hash.
+    
+    if opts[:keys]
+      got = @ndev.rpc.get_license_key_information
+      got.xpath('license-key').each do |key|
+        name = key.xpath('name').text.strip
+        ret_h[name][:key] = key.xpath('key-data').text
+      end
+    end    
+    
+    ret_h
+  end
+
+  ## ----------------------------------------------------------------  
+  ## add a license 
+  ##
+  ## --- returns ---
+  ## true - key added OK
+  ## String - error message otherwise
+  ##
+  ## --- options ---
+  ## :key => String
+  ##    The key text
+  ##
+  ## :filename => String
+  ##    Path to licence-file on server
+  ## ----------------------------------------------------------------
+  
+  def license_install!( opts = {} )
+    args = {}
+    if opts[:key]
+      args[:key_data] = opts[:key]
+    elsif opts[:filename]
+      args[:key_data] = File.read(opts[:filename]).strip
+    end
+    got = @ndev.rpc.request_license_add( args )
+    success = got.xpath('add-success')[0]
+    return true if success
+    got.xpath('//message').text.strip
+  end
+
+  ## ----------------------------------------------------------------  
+  ## remove a license 
+  ##
+  ## license_id is the String license-id or the special name :all
+  ## ----------------------------------------------------------------
+  
+  def license_rm!( license_id )
+    args = {}
+    if license_id == :all
+      args[:all] = true
+    else
+      args[:license_identifier] = license_id
+    end
+    got = @ndev.rpc.request_license_delete( args )
+    ### @@@ need to test return cases ... for now, just return
+    ### the 'got' XML
+    got
+  end
+
+  ## ----------------------------------------------------------------  
+  ## save licenses (plr!) to a file 
+  ## ----------------------------------------------------------------
+  
+  def license_save( opts = {} )
+    raise StandardError, "not implemented yet"
+  end
+  
 end
 
 ### -----------------------------------------------------------------

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: junos-ez-stdlib
 version: !ruby/object:Gem::Version
-  version: 0.0.15
+  version: 0.0.16
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-02 00:00:00.000000000 Z
+date: 2013-05-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: netconf