ruby-jss 0.6.3

data/lib/jss/ruby_extensions/hash.rb

@@ -0,0 +1,79 @@
+### Copyright 2016 Pixar
+###  
+###    Licensed under the Apache License, Version 2.0 (the "Apache License")
+###    with the following modification; you may not use this file except in
+###    compliance with the Apache License and the following modification to it:
+###    Section 6. Trademarks. is deleted and replaced with:
+###  
+###    6. Trademarks. This License does not grant permission to use the trade
+###       names, trademarks, service marks, or product names of the Licensor
+###       and its affiliates, except as required to comply with Section 4(c) of
+###       the License and to reproduce the content of the NOTICE file.
+###  
+###    You may obtain a copy of the Apache License at
+###  
+###        http://www.apache.org/licenses/LICENSE-2.0
+###  
+###    Unless required by applicable law or agreed to in writing, software
+###    distributed under the Apache License with the above modification is
+###    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+###    KIND, either express or implied. See the Apache License for the specific
+###    language governing permissions and limitations under the Apache License.
+### 
+###
+
+###
+class Hash
+
+  ###
+  ### Convert Hash values to nil.
+  ###
+  ### With no block, values equalling the String, or any member of the Array, given
+  ### will be converted to nil. Equality is evaluated with == and Array#include?
+  ###
+  ### With a block, if the result of the block evaluates to true, the value is converted to nil.
+  ###
+  ### Subhashes are ignored unless recurse is true.
+  ###
+  ### @param to_nils[String,Array] Hash values equal to (==) these become nil. Defaults to empty string
+  ###
+  ### @param recurse[Boolean] should sub-Hashes be nillified?
+  ###
+  ### @yield [value] Hash values for which the block returns true will become nil.
+  ###
+  ### @return [Hash] the hash with the desired values converted to nil
+  ###
+  ### @example
+  ###   hash = {:foo => '', :bar => {:baz => '' }}
+  ###   hash.jss_nillify!  # {:foo => nil, :bar => {:baz => '' }}
+  ###
+  ###   hash = {:foo => '', :bar => {:baz => '' }}
+  ###   hash.jss_nillify! '', :recurse  # {:foo => nil, :bar => {:baz => nil }}
+  ###
+  ###   hash = {:foo => 123, :bar => {:baz => '', :bim => "123" }}
+  ###   hash.jss_nillify! ['', 123], :recurse # {:foo => nil, :bar => {:baz => nil, :bim => "123" }}
+  ###
+  ###   hash = {:foo => 123, :bar => {:baz => '', :bim => "123" }}
+  ###   hash.jss_nillify!(:anything, :recurse){|v| v.to_i == 123 }  # {:foo => nil, :bar => {:baz => '', :bim => nil }}
+  ###
+  def jss_nillify!(to_nils = '', recurse = false, &block )
+
+    nillify_these = [] << to_nils
+    nillify_these.flatten!
+
+    self.each_pair do |k,v|
+      if v.class == Hash
+        v.jss_nillify!(to_nils, recurse, &block)
+        next
+      end
+      do_it = if block_given?
+        yield v
+      else
+        nillify_these.include? v
+      end
+      self[k] = nil if do_it
+    end # each pair
+  end # def nillify
+end # class
+
+

data/lib/jss/ruby_extensions/ipaddr.rb

@@ -0,0 +1,91 @@
+### Copyright 2016 Pixar
+###  
+###    Licensed under the Apache License, Version 2.0 (the "Apache License")
+###    with the following modification; you may not use this file except in
+###    compliance with the Apache License and the following modification to it:
+###    Section 6. Trademarks. is deleted and replaced with:
+###  
+###    6. Trademarks. This License does not grant permission to use the trade
+###       names, trademarks, service marks, or product names of the Licensor
+###       and its affiliates, except as required to comply with Section 4(c) of
+###       the License and to reproduce the content of the NOTICE file.
+###  
+###    You may obtain a copy of the Apache License at
+###  
+###        http://www.apache.org/licenses/LICENSE-2.0
+###  
+###    Unless required by applicable law or agreed to in writing, software
+###    distributed under the Apache License with the above modification is
+###    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+###    KIND, either express or implied. See the Apache License for the specific
+###    language governing permissions and limitations under the Apache License.
+### 
+###
+
+############################################
+### A few augmentations to IPAddr handling.
+###
+class IPAddr
+  
+  ### Convert starting and ending IPv4 IP addresses (either Strings or IPAddrs)
+  ### into a single masked IPv4 IPAddr
+  ###
+  ### @param starting[Strings, IPAddr] the starting IP address
+  ###
+  ### @param ending[Strings, IPAddr] the ending IP address
+  ###
+  ### @return [IPAddr] the IP address range represented as a masked IPv4 address
+  ###
+  ### @example
+  ###   IPAddr.jss_masked_v4addr '10.0.0.0', '10.0.0.255' # => #<IPAddr: IPv4:10.0.0.0/255.255.255.0>
+  ###
+  def self.jss_masked_v4addr(starting,ending)
+    IPAddr.new "#{starting}/#{self.jss_cidr_from_ends(starting,ending)}"
+  end #self.jss_masked_v4addr(starting,ending)
+  
+  ### Given starting and ending IPv4 IP addresses (either Strings or IPAddrs)
+  ### return the CIDR notation routing prefix mask
+  ###
+  ### @param starting[Strings, IPAddr] the starting IP address
+  ###
+  ### @param ending[Strings, IPAddr] the ending IP address
+  ###
+  ### @return [FixNum] the CIDR notation routing prefix mask
+  ###
+  ### @example
+  ###   IPAddr.jss_cidr_from_ends '10.0.0.0', '10.0.0.255' # => 24
+  ###
+  def self.jss_cidr_from_ends(starting,ending)
+    
+    starting = IPAddr.new(starting) unless starting.kind_of? IPAddr
+    ending = IPAddr.new(ending) unless ending.kind_of? IPAddr
+    
+    ### how many possible addresses in the range?
+    num_addrs =  ending.to_i - starting.to_i + 1
+    
+    ### convert the number of possible addresses to 
+    ### binary then subtract the number of bits from
+    ### the full length of an IPv4 addr 
+    ### (32 bits) and that gives the CIDR prefix
+    return 32 - num_addrs.to_s(2).length + 1
+    
+  end #self.get_cidr(starting,ending)
+
+  ### Convert a starting address (either String or IPAddr) and a 
+  ### CIDR notation routing prefix mask into the IPv4 address
+  ### of at the end of the range of addresses.
+  ###
+  ### @param starting[Strings, IPAddr] the starting IP address
+  ###
+  ### @param cidr[FixNum] the CIDR mask
+  ###
+  ### @return [IPAddr] the ending IP address of the range.
+  ###
+  ### @example
+  ###   IPAddr.jss_ending_address '10.0.0.0', 24 # => #<IPAddr: IPv4:10.0.0.255>
+  ###
+  def self.jss_ending_address(starting, cidr)
+    IPAddr.new( "#{starting}/#{cidr}").to_range.max
+  end # ending_address
+    
+end # Class IPAddr

data/lib/jss/ruby_extensions/pathname.rb

@@ -0,0 +1,77 @@
+### Copyright 2016 Pixar
+###  
+###    Licensed under the Apache License, Version 2.0 (the "Apache License")
+###    with the following modification; you may not use this file except in
+###    compliance with the Apache License and the following modification to it:
+###    Section 6. Trademarks. is deleted and replaced with:
+###  
+###    6. Trademarks. This License does not grant permission to use the trade
+###       names, trademarks, service marks, or product names of the Licensor
+###       and its affiliates, except as required to comply with Section 4(c) of
+###       the License and to reproduce the content of the NOTICE file.
+###  
+###    You may obtain a copy of the Apache License at
+###  
+###        http://www.apache.org/licenses/LICENSE-2.0
+###  
+###    Unless required by applicable law or agreed to in writing, software
+###    distributed under the Apache License with the above modification is
+###    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+###    KIND, either express or implied. See the Apache License for the specific
+###    language governing permissions and limitations under the Apache License.
+### 
+###
+
+############################################
+### Some handy additions to the Pathname class.
+### Why aren't they there already?
+###
+class Pathname
+  
+  ### Is this a real file rather than a symlink?
+  ### @see FileTest.real_file
+  def jss_real_file?
+    FileTest.jss_real_file? self 
+  end # real_file?
+  
+  ### Copy a path to a destination
+  ### @see FileUtils.cp
+  def jss_cp(dest, options = {})
+    FileUtils.cp @path, dest.to_s, options
+  end # cp
+  
+  ### Recursively copy this path to a destination
+  ### @see FileUtils.cp_r
+  def jss_cp_r(dest, options = {})
+    FileUtils.cp_r @path, dest.to_s, options
+  end # cp
+  
+  ### Write some string content to a file.
+  ###
+  ### Simpler than always using an open('w') block 
+  ### *CAUTION* this overwrites files!
+  ###
+  def jss_save(content)
+    self.open('w'){|f| f.write content.to_s}
+  end
+  
+  ### Append some string content to a file.
+  ###
+  ### Simpler than always using an open('a') block
+  ###
+  def jss_append(content)
+    self.open('a'){|f| f.write content.to_s}
+  end
+
+  ### Touching can be good 
+  ###
+  ### @see FileUtils.touch
+  def jss_touch
+    FileUtils.touch @path
+  end
+  
+  ### Pathname should use FileUtils.chown, not File.chown
+  def jss_chown(u,g)
+    FileUtils.chown u, g, @path
+  end
+end # class Pathname

data/lib/jss/ruby_extensions/string.rb

@@ -0,0 +1,59 @@
+### Copyright 2016 Pixar
+###  
+###    Licensed under the Apache License, Version 2.0 (the "Apache License")
+###    with the following modification; you may not use this file except in
+###    compliance with the Apache License and the following modification to it:
+###    Section 6. Trademarks. is deleted and replaced with:
+###  
+###    6. Trademarks. This License does not grant permission to use the trade
+###       names, trademarks, service marks, or product names of the Licensor
+###       and its affiliates, except as required to comply with Section 4(c) of
+###       the License and to reproduce the content of the NOTICE file.
+###  
+###    You may obtain a copy of the Apache License at
+###  
+###        http://www.apache.org/licenses/LICENSE-2.0
+###  
+###    Unless required by applicable law or agreed to in writing, software
+###    distributed under the Apache License with the above modification is
+###    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+###    KIND, either express or implied. See the Apache License for the specific
+###    language governing permissions and limitations under the Apache License.
+### 
+###
+
+###
+class String
+  
+  ### Convert the strings "true" and "false" 
+  ### (after stripping whitespace and downcasing)
+  ### to TrueClass and FalseClass respectively
+  ### 
+  ### Return nil if any other string.
+  ###
+  ### @return [Boolean,nil] the boolean value
+  ###
+  def jss_to_bool
+    case self.strip.downcase
+      when "true" then return true
+      when "false" then return false
+      else return nil
+    end # case
+  end # to bool
+  
+  ### Convert a string to a Time object
+  ###
+  ### returns nil if not parsable by JSS::parse_datetime
+  ###
+  ### @return [Time] the time represented by the string.
+  ###
+  def jss_to_time
+    begin
+      JSS.parse_time self
+    rescue
+      return nil
+    end
+  end
+
+  
+end # class

data/lib/jss/ruby_extensions/time.rb

@@ -0,0 +1,63 @@
+### Copyright 2016 Pixar
+###  
+###    Licensed under the Apache License, Version 2.0 (the "Apache License")
+###    with the following modification; you may not use this file except in
+###    compliance with the Apache License and the following modification to it:
+###    Section 6. Trademarks. is deleted and replaced with:
+###  
+###    6. Trademarks. This License does not grant permission to use the trade
+###       names, trademarks, service marks, or product names of the Licensor
+###       and its affiliates, except as required to comply with Section 4(c) of
+###       the License and to reproduce the content of the NOTICE file.
+###  
+###    You may obtain a copy of the Apache License at
+###  
+###        http://www.apache.org/licenses/LICENSE-2.0
+###  
+###    Unless required by applicable law or agreed to in writing, software
+###    distributed under the Apache License with the above modification is
+###    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+###    KIND, either express or implied. See the Apache License for the specific
+###    language governing permissions and limitations under the Apache License.
+### 
+###
+
+############################################
+### The JSS API can take incoming timestamp data in three formats:
+### - plain date: YYYY-mm-dd HH:MM:SS, which is assumed to be in the local timezone
+### - UTC date: YYYY-mm-ddTHH:MM:SS.mmm [+-]zzzz, the local time with milliseconds and the timezone offset
+### - Unix epoch with milliseconds, nnnnnnnnnnnnn,  which like all epoch times, is UTC
+###
+### Here we extend Time to return the three formats for use in XML data to pass
+### back to the API. The API xml works with any of the formats, in appropriate elements.
+###
+### Generally this gem uses the epoch format for passing values back to the API, just to help avoid
+### timezone weirdness, but any should work.
+###
+### When reading from the API, all three formats are returned in different xml elements,
+### and the APIObjects in the gem will use the epoch format and the JSS.epoch_to_time method (q.v.) to store
+### the data as a Ruby Time.
+###
+class Time
+
+  ### @return [Integer] the milliseconds of the Time
+  def jss_msec
+    (self.usec/1000.0).round
+  end
+
+  ### @return [Integer] The Time as a unix epoch with milliseconds appended
+  def to_jss_epoch
+    (self.strftime('%s') + self.jss_msec.to_s.ljust(3,'0')).to_i
+  end
+
+  ### @return [String] the Time formatted for a plain JSS XML date element
+  def to_jss_date
+    self.strftime '%Y-%m-%d %H:%M:%S'
+  end
+
+  ### @return [String] the Time formatted for a JSS UTC XML date element
+  def to_jss_utc
+    self.strftime("%Y-%m-%dT%H:%M:%S.#{self.jss_msec}%z")
+  end
+
+end

data/lib/jss/server.rb

@@ -0,0 +1,108 @@
+### Copyright 2016 Pixar
+###  
+###    Licensed under the Apache License, Version 2.0 (the "Apache License")
+###    with the following modification; you may not use this file except in
+###    compliance with the Apache License and the following modification to it:
+###    Section 6. Trademarks. is deleted and replaced with:
+###  
+###    6. Trademarks. This License does not grant permission to use the trade
+###       names, trademarks, service marks, or product names of the Licensor
+###       and its affiliates, except as required to comply with Section 4(c) of
+###       the License and to reproduce the content of the NOTICE file.
+###  
+###    You may obtain a copy of the Apache License at
+###  
+###        http://www.apache.org/licenses/LICENSE-2.0
+###  
+###    Unless required by applicable law or agreed to in writing, software
+###    distributed under the Apache License with the above modification is
+###    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+###    KIND, either express or implied. See the Apache License for the specific
+###    language governing permissions and limitations under the Apache License.
+### 
+###
+
+###
+module JSS
+
+  ### A class representing a JSS Server.
+  ###
+  ### The {JSS::APIConnection} instance has a JSS::Server instance in its @server attribute.
+  ### It is created fresh every time {APIConnection#connect} is called.
+  ###
+  ### That's the only time it should be instantiated, and all access should be through
+  ### {JSS::API.server}
+  ###
+  class Server
+
+    #####################################
+    ### Attributes
+    #####################################
+
+    ### @return [String] the organization to which the server is licensed
+    attr_reader :organization
+    
+
+    ### @return [String] the activation code for the server licence
+    attr_reader :activation_code
+
+    ### @return [String] the type of server licence
+    attr_reader :license_type
+
+    ### @return [String] the license product name
+    attr_reader :product
+
+    ###  @return [String] The version of the JSS. See the method JSS.parse_jss_version
+    attr_reader :version
+
+    ###  @return [Integer]
+    attr_reader :major_version
+
+    ###  @return [Integer]
+    attr_reader :minor_version
+
+    ###  @return [Integer]
+    attr_reader :revision_version
+
+    ###  @return [String]
+    attr_reader :raw_version
+
+    #####################################
+    ### Instance Methods
+    #####################################
+
+    ###
+    ### Initialize!
+    ###
+    def initialize
+      begin
+
+        # the jssuser resource is readable by anyone with a JSS acct
+        # regardless of their permissions.
+        # However, it's marked as 'deprecated'. Hopefully jamf will
+        # keep this basic level of info available for basic authentication
+        # and JSS version checking.
+        ju = JSS::API.get_rsrc('jssuser')[:user]
+        @license_type = ju[:license_type]
+        @product = ju[:product]
+        @raw_version = ju[:version]
+        parsed = JSS.parse_jss_version(@raw_version)
+        @major_version = parsed[:major]
+        @minor_version = parsed[:minor]
+        @revision_version = parsed[:revision]
+        @version = parsed[:version]
+
+      rescue RestClient::Request::Unauthorized
+        raise JSS::AuthenticationError, "Incorrect JSS username or password for '#{JSS::API.jss_user}@#{JSS::API.server_host}'."
+      end
+
+    end
+
+    
+    ##### Aliases
+    alias institution organization
+    alias product_name product
+    
+  end # class server
+
+end # module