ruby-jss 1.2.4a4 → 1.3.3

data/lib/jss/api_object/netboot_server.rb

@@ -1,4 +1,4 @@
-### Copyright 2019 Pixar
+### Copyright 2020 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")

data/lib/jss/api_object/network_segment.rb

@@ -1,4 +1,4 @@
-### Copyright 2019 Pixar
+### Copyright 2020 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -67,21 +67,70 @@ module JSS
     ### Class Methods
     #####################################
 
-    ### All NetworkSegments in the jss as IPAddr object Ranges representing the
-    ### Segment, e.g. with starting = 10.24.9.1 and ending = 10.24.15.254
-    ### the range looks like:
-    ###   <IPAddr: IPv4:10.24.9.1/255.255.255.255>..#<IPAddr: IPv4:10.24.15.254/255.255.255.255>
-    ###
-    ### Using the #include? method on those Ranges is very useful.
-    ###
-    ### @param refresh[Boolean] re-read the data from the API?
-    ###
-    ### @param api[JSS::APIConnection] The API connection to query
-    ###
-    ### @return [Hash{Integer => Range}] the network segments as IPv4 address Ranges
-    ###
+    # All NetworkSegments in the given API as ruby Ranges of IPAddr instances
+    # representing the Segment,
+    # e.g. with starting = 10.24.9.1 and ending = 10.24.15.254
+    # the range looks like:
+    #  <IPAddr: IPv4:10.24.9.1/255.255.255.255>
+    #   ..
+    #  <IPAddr: IPv4:10.24.15.254/255.255.255.255>
+    #
+    # Using the #include? method on those Ranges is very useful.
+    #
+    # Note1: We don't use the IPAddr#to_range method because that works
+    #   best for masked IPAddrs (which are ranges of IPs with widths
+    #   determined by the mask) and Jamf Network Segments can have arbitrary
+    #   widths.
+    #
+    # Note2: See the network_ranges_as_integers method below, which is similar
+    #   but much faster.
+    #
+    # @param refresh[Boolean] should the data be re-queried?
+    #
+    # @param api[JSS::APIConnection] the API to query
+    #
+    # @return [Hash{Integer => Range}] the network segments as IPv4 address Ranges
+    #   keyed by id
+    #
     def self.network_ranges(refresh = false, api: JSS.api)
-      api.network_ranges refresh
+      @network_ranges = nil if refresh
+      return @network_ranges if @network_ranges
+
+      @network_ranges = {}
+      all(refresh, api: api).each do |ns|
+        @network_ranges[ns[:id]] = IPAddr.new(ns[:starting_address])..IPAddr.new(ns[:ending_address])
+      end
+      @network_ranges
+    end # def network_segments
+
+    # An IPv4 Address is really just a 32-bit integer, displayed as four
+    # 8-bit integers. e.g. '10.0.69.1' is really the integer 167789825
+    # The #to_i method of IPAddr objects returns that integer (or the first of
+    # them if the IPAddr is masked).
+    #
+    # Using ranges made of those integers is far faster than using ranges
+    # if IPAddr objects, so that's what this method returns.
+    #
+    # See also: the network_ranges method above
+    #
+    # @param refresh[Boolean] should the data be re-queried?
+    #
+    # @param api[JSS::APIConnection] the APIConnection to query
+    #
+    # @return [Hash{Integer => Range}] the network segments as Integer Ranges
+    #   keyed by id
+    #
+    def self.network_ranges_as_integers(refresh = false, api: JSS.api)
+      @network_ranges_as_integers = nil if refresh
+      return @network_ranges_as_integers if @network_ranges_as_integers
+
+      @network_ranges_as_integers = {}
+      all(refresh, api: api).each do |ns|
+        first = IPAddr.new(ns[:starting_address]).to_i
+        last = IPAddr.new(ns[:ending_address]).to_i
+        @network_ranges_as_integers[ns[:id]] = first..last
+      end
+      @network_ranges_as_integers
     end # def network_segments
 
     ### An alias for {NetworkSegment.network_ranges}
@@ -195,23 +244,72 @@ module JSS
     ###
     ### @return [Array<Integer>] the ids of the NetworkSegments containing the given ip
     ###
-    def self.network_segments_for_ip(ip, refresh = false, api: JSS.api)
-      ok_ip = IPAddr.new(ip)
-      matches = []
-      network_ranges(refresh, api: api).each { |id, subnet| matches << id if subnet.include?(ok_ip) }
-      matches
+    def self.network_segments_for_ip(ipaddr, refresh = false, api: JSS.api)
+      # get the ip as a 32bit interger
+      ip = IPAddr.new(ipaddr.to_s).to_i
+      # a hash of NetSeg ids => Range<Integer>
+      network_ranges_as_integers(refresh, api: api).select { |_id, range| range.include? ip }.keys
+    end
+
+    # Which network segment is seen as current for a given IP addr?
+    #
+    # According to the Jamf Pro Admin Guide, if an IP is in more than one network
+    # segment, it uses the 'smallest' (narrowest) one - the one with fewest
+    # IP addrs within it.
+    #
+    # If multiple ones have the same width, then it uses the one of
+    # those with the lowest starting address
+    #
+    # @return [Integer, nil] the id of the current net segment, or nil
+    #
+    def self.network_segment_for_ip(ipaddr, refresh: false, api: JSS.api)
+      # get the ip as a 32bit interger
+      ip = IPAddr.new(ipaddr.to_s).to_i
+      # a hash of NetSeg ids => Range<Integer>
+      ranges = network_ranges_as_integers(refresh, api: api).select { |_id, range| range.include? ip }
+
+      # we got nuttin
+      return nil if ranges.empty?
+
+      # if we got only one, its the one
+      return ranges.keys.first if ranges.size == 1
+
+      # got more than one, sort by range size/width, asc.
+      sorted_by_size = ranges.sort_by { |_i, r| r.size }.to_h
+
+      # the first one is the smallest/narrowest.
+      _smallest_range_id, smallest_range = sorted_by_size.first
+
+      smallest_range_size = smallest_range.size
+
+      # select all of them that are the same size
+      all_of_small_size = sorted_by_size.select { |_i, r| r.size == smallest_range_size }
+
+      # sort them by the start of each range (r.first)
+      # and return the lowest start (returned by min_by)
+      my_range_id, _my_range = all_of_small_size.min_by { |_i, r| r.first }
+
+      # and return the id
+      my_range_id
     end
 
-    # @deprecated use network_segments_for_ip
-    # Here for Backward compatibility
-    def self.network_segment_for_ip(ip, api: JSS.api)
-      network_segments_for_ip(ip, api: api)
+    # given 2 IPAddr instances, find out how 'wide' they are -
+    # how many IP addresses exist between them.
+    def self.ip_range_width(ip1, ip2)
+      raise ArgumentError, 'Parameters must be IPAddr objects' unless ip1.is_a?(IPAddr) && ip2.is_a?(IPAddr)
+
+      low, high = [ip1, ip2].sort
+      high.to_i - low.to_i
     end
 
-    ### Find the current network segment ids for the machine running this code
-    ###
-    ### @return [Array<Integer>] the NetworkSegment ids for this machine right now.
-    ###
+    # Find the current network segment ids for the machine running this code
+    #
+    # See my_network_segment to get the current one according to the server.
+    #
+    # @param names [Boolean] the array will contain Network Segment names, not ids
+    #
+    # @return [Array<Integer>,Array<String>] the NetworkSegment ids or names for this machine right now.
+    #
     def self.my_network_segments(refresh = false, names: false, api: JSS.api)
       ids = network_segments_for_ip JSS::Client.my_ip_address, refresh, api: api
       return ids unless names
@@ -220,35 +318,23 @@ module JSS
       ids.map { |id| ids_to_names[id] }
     end
 
-    # @deprecated use my_network_segments
-    # Here for backward compatibility
-    def self.my_network_segment(api: JSS.api)
-      my_network_segments api: api
-    end
-
-    # All NetworkSegments in the given API as IPAddr object Ranges representing the
-    # Segment, e.g. with starting = 10.24.9.1 and ending = 10.24.15.254
-    # the range looks like:
-    #   <IPAddr: IPv4:10.24.9.1/255.255.255.255>..#<IPAddr: IPv4:10.24.15.254/255.255.255.255>
+    # Which network segment is seen as current? According to the
+    # Jamf Pro Admin Guide, the 'smallest' one - the one with fewest IP
+    # addrs within it.  If multiple ones have the same number of IPs,
+    # then its the one with the lowest starting address
     #
-    # Using the #include? method on those Ranges is very useful.
+    # @param name [Boolean] return the name of the netsegment, not the id
     #
-    # @param refresh[Boolean] should the data be re-queried?
-    #
-    # @param api[JSS::APIConnection] the API to query
-    #
-    # @return [Hash{Integer => Range}] the network segments as IPv4 address Ranges
-    #   keyed by id
-    #
-    def self.network_ranges(refresh = false, api: JSS.api)
-      @network_ranges = nil if refresh
-      return @network_ranges if @network_ranges
-      @network_ranges = {}
-      all(refresh, api: api).each do |ns|
-        @network_ranges[ns[:id]] = IPAddr.new(ns[:starting_address])..IPAddr.new(ns[:ending_address])
-      end
-      @network_ranges
-    end # def network_segments
+    # @return [Integer, String, nil] the id of the current net segment, or nil
+    def self.my_network_segment(refresh = false, name: false, api: JSS.api)
+      my_ip = JSS::Client.my_ip_address
+      return nil unless my_ip
+
+      id = network_segment_for_ip(my_ip, refresh: refresh, api: api)
+      return id unless name
+
+      map_all_ids_to(:name)[id]
+    end
 
     ### Attributes
     #####################################
@@ -419,14 +505,22 @@ module JSS
 
     ### set the distribution_point
     ###
-    ### @param newval[String, Integer] the new dist. point by name or id, must be in the JSS
+    ### @param newval[String, Integer, nil] the new dist. point by name or id, must be in the JSS, or nil  or blank to unset
     ###
     ### @return [void]
     ###
     def distribution_point=(newval)
-      new = JSS::DistributionPoint.all.select { |b| (b[:id] == newval) || (b[:name] == newval) }[0]
-      raise JSS::MissingDataError, "No distribution_point matching '#{newval}' in the JSS" unless new
-      @distribution_point = new[:name]
+      new =
+        if newval.to_s.empty?
+          JSS::BLANK
+        else
+          id = JSS::DistributionPoint.valid_id newval
+          raise JSS::MissingDataError, "No distribution_point matching '#{newval}' in the JSS" unless id
+
+          JSS::DistributionPoint.map_all_ids_to(:name)[id]
+        end
+
+      @distribution_point = new
       @need_to_update = true
     end
 

data/lib/jss/api_object/package.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Pixar
+# Copyright 2020 Pixar
 
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -121,9 +121,31 @@ module JSS
     # @return [Array<String>] The current file names
     #
     def self.all_filenames(api: JSS.api)
-      pkgs_in_use = []
-      all_ids.each { |pkg_id| pkgs_in_use << fetch(id: pkg_id, api: api).filename }
-      pkgs_in_use.compact
+      all_filenames_by(:id, api: api).values
+    end
+
+    # A Hash of all dist-point filenames used by all JSS packages, keyed by
+    # package name or id
+    #
+    # Slow cuz we have to instantiate every pkg
+    #
+    # @param key[Symbol] either :id, or :name
+    #
+    # @param api[JSS::APIConnection] an API connection to use
+    #   Defaults to the corrently active API. See {JSS::APIConnection}
+    #
+    # @return [Hash{Ingeter,String => String}] The current file names by key
+    #
+    def self.all_filenames_by(key, api: JSS.api)
+      raise ArgumentError, 'key must be :id or :name' unless %i[id name].include? key
+
+      files_in_use = {}
+      all_ids(:refresh).each do |pkg_id|
+        pkg = fetch id: pkg_id, api: api
+        files_in_use[pkg.send(key)] = pkg.filename
+      end
+
+      files_in_use
     end
 
     # An array of String filenames for all files DIST_POINT_PKGS_FOLDER
@@ -140,14 +162,17 @@ module JSS
     # @param api[JSS::APIConnection] an API connection to use
     #   Defaults to the corrently active API. See {JSS::APIConnection}
     #
+    # @param dist_point [String,Integer] the name or id of the distribution
+    #   point to use. Defaults to the Master Dist. Point
+    #
     # @return [Array<String>] The orphaned files
     #
-    def self.orphaned_files(ro_pw, unmount = true, api: JSS.api)
-      mdp = JSS::DistributionPoint.master_distribution_point api: api
-      pkgs_dir = mdp.mount(ro_pw, :ro) + DIST_POINT_PKGS_FOLDER
-      files_on_mdp = pkgs_dir.children.map { |f| f.basename.to_s }
-      mdp.unmount if unmount
-      files_on_mdp - all_filenames(api: api)
+    def self.orphaned_files(ro_pw, unmount = true, api: JSS.api, dist_point: nil)
+      dp = fetch_dist_point(dist_point, api: api)
+      pkgs_dir = dp.mount(ro_pw, :ro) + DIST_POINT_PKGS_FOLDER
+      files_on_dp = pkgs_dir.children.map { |f| f.basename.to_s }
+      dp.unmount if unmount
+      files_on_dp - all_filenames(api: api)
     end
 
     # An array of String filenames for all filenames in any
@@ -164,14 +189,18 @@ module JSS
     # @param api[JSS::APIConnection] an API connection to use
     #   Defaults to the corrently active API. See {JSS::APIConnection}
     #
+    # @param dist_point [String,Integer] the name or id of the distribution
+    #   point to use. Defaults to the Master Dist. Point
+    #
+    #
     # @return [Array<String>] The orphaned files
     #
-    def self.missing_files(ro_pw, unmount = true, api: JSS.api)
-      mdp = JSS::DistributionPoint.master_distribution_point api: api
-      pkgs_dir = mdp.mount(ro_pw, :ro) + DIST_POINT_PKGS_FOLDER
-      files_on_mdp = pkgs_dir.children.map { |f| f.basename.to_s }
-      mdp.unmount if unmount
-      all_filenames(api: api) - files_on_mdp
+    def self.missing_files(ro_pw, unmount = true, api: JSS.api, dist_point: nil)
+      dp = fetch_dist_point(dist_point, api: api)
+      pkgs_dir = dp.mount(ro_pw, :ro) + DIST_POINT_PKGS_FOLDER
+      files_on_dp = pkgs_dir.children.map { |f| f.basename.to_s }
+      dp.unmount if unmount
+      all_filenames(api: api) - files_on_dp
     end
 
     # Given a file path, and hash type, generate the checksum for an arbitrary
@@ -189,6 +218,18 @@ module JSS
       CHECKSUM_HASH_TYPES[type].file(filepath).hexdigest
     end
 
+    # @param dist_point [String,Integer] the name or id of the distribution
+    #   point to use. Defaults to the Master Dist. Point
+    #
+    # @return [JSS::DistributionPoint]
+    def self.fetch_dist_point(dist_point, api: JSS.api)
+      if dist_point
+        JSS::DistributionPoint.fetch dist_point, api: api
+      else
+        JSS::DistributionPoint.master_distribution_point api: api
+      end
+    end
+
     # Attributes
     #####################################
 
@@ -324,7 +365,7 @@ module JSS
       new_val = nil if new_val == ''
       new_val ||= @name
       return nil if new_val == @filename
-      warn 'WARNING: you must change the filename on the master Distribution Point. See JSS::Package.update_master_filename.' if @in_jss
+
       @filename = new_val
       @need_to_update = true
     end
@@ -590,13 +631,17 @@ module JSS
     # @param chksum [String] the constants CHECKSUM_HASH_TYPE_SHA512 or
     #   CHECKSUM_HASH_TYPE_MD5. Anything else means don't calc.
     #
+    # @param dist_point [String,Integer] the name or id of the distribution
+    #   point to use. Defaults to the Master Dist. Point
+    #
     # @return [void]
     #
-    def upload_master_file(local_file_path, rw_pw, unmount = true, chksum: DEFAULT_CHECKSUM_HASH_TYPE )
+    def upload_master_file(local_file_path, rw_pw, unmount = true, chksum: DEFAULT_CHECKSUM_HASH_TYPE, dist_point: nil)
       raise JSS::NoSuchItemError, 'Please create this package in the JSS before uploading it.' unless @in_jss
 
-      mdp = JSS::DistributionPoint.master_distribution_point api: @api
-      destination = mdp.mount(rw_pw, :rw) + "#{DIST_POINT_PKGS_FOLDER}/#{@filename}"
+      dp = self.class.fetch_dist_point(dist_point, api: @api)
+
+      destination = dp.mount(rw_pw, :rw) + "#{DIST_POINT_PKGS_FOLDER}/#{@filename}"
 
       local_path = Pathname.new local_file_path
       raise JSS::NoSuchItemError, "Local file '#{@local_file}' doesn't exist" unless local_path.exist?
@@ -637,11 +682,11 @@ module JSS
 
       if CHECKSUM_HASH_TYPES.keys.include? chksum
         @checksum_type = chksum
-        @checksum = calculate_checksum local_file: local_path, type: chksum, unmount: false
+        @checksum = calculate_checksum local_file: local_path, type: chksum, unmount: false, dist_point: dist_point
         @need_to_update = true
       end
       update if @need_to_update
-      mdp.unmount if unmount
+      dp.unmount if unmount
     end # upload master file
 
     # Using either a local file, or the file on the master dist. point,
@@ -658,7 +703,7 @@ module JSS
     #
     # @return [void]
     #
-    def reset_checksum(type: nil, local_file: nil, rw_pw: nil, ro_pw: nil, unmount: true)
+    def reset_checksum(type: nil, local_file: nil, rw_pw: nil, ro_pw: nil, unmount: true, dist_point: nil )
       type ||= DEFAULT_CHECKSUM_HASH_TYPE
 
       new_checksum = calculate_checksum(
@@ -666,7 +711,8 @@ module JSS
         local_file: local_file,
         rw_pw: rw_pw,
         ro_pw: ro_pw,
-        unmount: unmount
+        unmount: unmount,
+        dist_point: dist_point
       )
       return if @checksum == new_checksum
 
@@ -694,11 +740,14 @@ module JSS
     # @param unmount [Boolean] Unmount the master dist point after using it.
     #   Only used if the dist point is mounted. default: true
     #
+    # @param dist_point [String,Integer] the name or id of the distribution
+    #   point to use. Defaults to the Master Dist. Point
+    #
     # @return [String] The calculated checksum
     #
-    def calculate_checksum(type: nil, local_file: nil, rw_pw: nil, ro_pw: nil, unmount: true )
+    def calculate_checksum(type: nil, local_file: nil, rw_pw: nil, ro_pw: nil, unmount: true, dist_point: nil )
       type ||= DEFAULT_CHECKSUM_HASH_TYPE
-      mdp = JSS::DistributionPoint.master_distribution_point api: @api
+      dp = self.class.fetch_dist_point(dist_point, api: @api)
 
       if local_file
         file_to_calc = local_file
@@ -712,10 +761,10 @@ module JSS
         else
           raise ArgumentError, 'Either rw_pw: or ro_pw: must be provided'
         end
-        file_to_calc = mdp.mount(dppw, mnt) + "#{DIST_POINT_PKGS_FOLDER}/#{@filename}"
+        file_to_calc = dp.mount(dppw, mnt) + "#{DIST_POINT_PKGS_FOLDER}/#{@filename}"
       end
       new_checksum = self.class.calculate_checksum(file_to_calc, type)
-      mdp.unmount if unmount && mdp.mounted?
+      dp.unmount if unmount && dp.mounted?
       new_checksum
     end
 
@@ -734,17 +783,21 @@ module JSS
     # @param unmount [Boolean] Unmount the master dist point after using it.
     #   Only used if the dist point is mounted. default: true
     #
+    # @param dist_point [String,Integer] the name or id of the distribution
+    #   point to use. Defaults to the Master Dist. Point
+    #
     # @return [Boolean] false if there is no checksum for this pkg, otherwise,
     #   does the calculated checksum match the one stored for the pkg?
     #
-    def checksum_valid?(local_file: nil, rw_pw: nil, ro_pw: nil, unmount: true)
+    def checksum_valid?(local_file: nil, rw_pw: nil, ro_pw: nil, unmount: true, dist_point: nil )
       return false unless @checksum
       new_checksum = calculate_checksum(
         type: @checksum_type,
         local_file: local_file,
         rw_pw: rw_pw,
         ro_pw: ro_pw,
-        unmount: unmount
+        unmount: unmount,
+        dist_point: dist_point
       )
       new_checksum == @checksum
     end
@@ -760,12 +813,16 @@ module JSS
     # @param rw_pw[String,Symbol] the password for the read/write account on the master Distribution Point,
     #   or :prompt, or :stdin# where # is the line of stdin containing the password See {JSS::DistributionPoint#mount}
     #
+    # @param dist_point [String,Integer] the name or id of the distribution
+    #   point to use. Defaults to the Master Dist. Point
+    #
     # @return [nil]
     #
-    def update_master_filename(old_file_name, new_file_name, rw_pw, unmount = true)
+    def update_master_filename(old_file_name, new_file_name, rw_pw, unmount = true, dist_point: nil)
       raise JSS::NoSuchItemError, "#{old_file_name} does not exist in the jss." unless @in_jss
-      mdp = JSS::DistributionPoint.master_distribution_point api: @api
-      pkgs_dir = mdp.mount(rw_pw, :rw) + DIST_POINT_PKGS_FOLDER.to_s
+      dp = self.class.fetch_dist_point(dist_point, api: @api)
+
+      pkgs_dir = dp.mount(rw_pw, :rw) + DIST_POINT_PKGS_FOLDER.to_s
       old_file = pkgs_dir + old_file_name
       raise JSS::NoSuchItemError, "File not found on the master distribution point at #{DIST_POINT_PKGS_FOLDER}/#{old_file_name}." unless \
         old_file.exist?
@@ -775,7 +832,7 @@ module JSS
       new_file = pkgs_dir + (new_file_name + old_file.extname) if new_file.extname.empty?
 
       old_file.rename new_file
-      mdp.unmount if unmount
+      dp.unmount if unmount
       nil
     end # update_master_filename
 
@@ -791,18 +848,21 @@ module JSS
     #
     # @param unmount[Boolean] whether or not ot unount the distribution point when finished.
     #
+    # @param dist_point [String,Integer] the name or id of the distribution
+    #   point to use. Defaults to the Master Dist. Point
+    #
     # @return [Boolean] was the file deleted?
     #
-    def delete_master_file(rw_pw, unmount = true)
-      mdp = JSS::DistributionPoint.master_distribution_point api: @api
-      file = mdp.mount(rw_pw, :rw) + "#{DIST_POINT_PKGS_FOLDER}/#{@filename}"
+    def delete_master_file(rw_pw, unmount = true, dist_point: nil)
+      dp = self.class.fetch_dist_point(dist_point, api: @api)
+      file = dp.mount(rw_pw, :rw) + "#{DIST_POINT_PKGS_FOLDER}/#{@filename}"
       if file.exist?
         file.delete
         did_it = true
       else
         did_it = false
       end # if exists
-      mdp.unmount if unmount
+      dp.unmount if unmount
       did_it
     end # delete master file
 
@@ -816,9 +876,13 @@ module JSS
     #
     # @param unmount[Boolean] whether or not ot unount the distribution point when finished.
     #
-    def delete(delete_file: false, rw_pw: nil, unmount: true)
+    # @param dist_point [String,Integer] the name or id of the distribution
+    #   point to use. Defaults to the Master Dist. Point
+    #
+    # @return [void]
+    def delete(delete_file: false, rw_pw: nil, unmount: true, dist_point: nil)
       super()
-      delete_master_file(rw_pw, unmount) if delete_file
+      delete_master_file(rw_pw, unmount, dist_point: dist_point) if delete_file
     end
 
     # Install this package via the jamf binary 'install' command from the
@@ -885,7 +949,7 @@ module JSS
 
         # we'll re-add the filename below if needed.
         src_path = args[:alt_download_url].chomp "/#{@filename}"
-
+        using_http = true
       # use our appropriate dist. point for download
       else
         mdp = JSS::DistributionPoint.my_distribution_point api: @api
@@ -1021,6 +1085,7 @@ module JSS
 
     private
 
+
     # Return the REST XML for this pkg, with the current values,
     # for saving or updating
     #