ruby-jss 1.2.3 → 1.2.4a1

data/lib/jamf/compatibility.rb

@@ -0,0 +1,88 @@
+# Copyright 2019 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.
+#
+#
+
+# backporting of some newer ruby methods into older rubies
+#
+
+# Hash.key
+#
+# #key exists in ruby 1.9+, in 1.8 its called #index
+# it returns the hash key for a given value, if the value exists
+# in the hash
+#
+###########################################
+unless {}.respond_to? :key
+  class Hash
+
+    alias key index
+
+  end
+end
+
+# Array.sample
+#
+# #sample exists in ruby 1.9+, in 1.8 its called #choice
+# it returns a randomly chosen element of the given array
+# eg: [1, 2, 3].sample returns either 1, 2, or 3
+#
+###########################################
+unless [].respond_to? :sample
+  class Array
+
+    alias sample choice
+
+  end
+end
+
+# String.force_encoding
+#
+#
+###########################################
+unless ''.respond_to? :force_encoding
+  class String
+
+    def force_encoding(_args = nil)
+      self
+    end
+
+  end
+end
+
+
+# String.casecmp?
+#
+#
+###########################################
+unless ''.respond_to? :casecmp?
+  class String
+
+    def casecmp?(other)
+      return nil unless other.is_a? String
+
+      casecmp(other).zero?
+    end
+
+  end
+end

data/lib/jamf/composer.rb

@@ -0,0 +1,190 @@
+### Copyright 2019 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 Jamf
+
+  ###
+  ### This module provides two methods for building very simple Casper-happy .pkg and .dmg packages for deployment.
+  ###
+  ### Unlike Composer.app from JAMF, this module currently doesn't offer a way to do a before/after disk scan
+  ### and use the differences to build the root folder from which the package is built. Nor does the module support
+  ### editing the pre/post install scripts in .pkgs.
+  ###
+  ### The 'root folder', a folder representing the root filesystem of the target machine where the package will be installed,
+  ### must already exist and be fully populated and with correct permissions.
+  ###
+  module Composer
+
+    #####################################
+    ### Constants
+    #####################################
+
+    ### the apple pkgutil tool
+    PKG_UTIL = Pathname.new '/usr/sbin/pkgutil'
+
+    ### The location of the cli tool for making .pkgs
+    PKGBUILD = Pathname.new '/usr/bin/pkgbuild'
+
+    ### the default bundle identifier prefix for pkgs
+    PKG_BUNDLE_ID_PFX = 'ruby-jss-composer'.freeze
+
+    ### Apple's hdiutil for making dmgs
+    HDI_UTIL = '/usr/bin/hdiutil'.freeze
+
+    ### Where to save the output ?
+    DEFAULT_OUT_DIR = Pathname.new '/Users/Shared'
+
+    ### Make a casper-happy .pkg out of a root folder, permissions are assumed to be correct.
+    ###
+    ### @param name[String] the name of the .pkg. The .pkg suffix will be added if not present
+    ###
+    ### @param version[String] the version of the .pkg, needed for building the .pkg
+    ###
+    ### @param root[String, Pathname] the path to the 'root folder' representing
+    ###   the root file system of the target install drive
+    ###
+    ### @param opts[Hash] the options for building the .pkg
+    ###
+    ### @options opts :pkg_id[String] the full package if for the new pkg.
+    ###   e.g. 'com.mycompany.myapp'
+    ###
+    ### @option opts :bundle_id_prefix[String] the pkg bundle identifier prefix.
+    ###   If no :pkg_id is provided, one is made using this prefix and
+    ###   the name provided. e.g. 'com.mycompany'
+    ###   Defaults to '{PKG_BUNDLE_ID_PFX}'. See 'man pkgbuild' for more info
+    ###
+    ### @option opts :out_dir[String,Pathname] he folder in which the .pkg will be
+    ###   created. Defaults to {DEFAULT_OUT_DIR}
+    ###
+    ### @option opts :preserve_ownership[Boolean] If true, the owner/group of the
+    ###   rootpath are preserved.
+    ###   Default is false: they become the pkgbuild/installer 'recommended'
+    ###   (root/wheel or root/admin)
+    ###
+    ### @option opts :signing_identity[String] the optional name of the signing identity (certificate) to
+    ###   use for signing the pkg. See `man pkgbuild` for details
+    ###
+    ### @option opts :signing_options[String] the optional string of options to pass to pkgbuild.
+    ###  See `man pkgbuild` for details
+    ###
+    ### @return [Pathname] the local path to the new .pkg
+    ###
+    def self.mk_pkg(name, version, root, opts = {})
+      raise NoSuchItemError, "Missing pkgbuild tool. Please make sure you're running 10.8 or later." unless PKGBUILD.executable?
+
+      opts[:out_dir] ||= DEFAULT_OUT_DIR
+      opts[:bundle_id_prefix] ||= PKG_BUNDLE_ID_PFX
+
+      pkg_filename = name.end_with?('.pkg') ? name : name + '.pkg'
+      pkg_id = opts[:pkg_id]
+      pkg_id ||= opts[:bundle_id_prefix] + '.' + name
+      pkg_out = "#{opts[:out_dir]}/#{pkg_filename}"
+      pkg_ownership = opts[:preserve_ownership] ? 'preserve' : 'recommended'
+
+      if opts[:signing_identity]
+        signing = "--sign '#{opts[:signing_identity]}'"
+        signing << " #{opts[:signing_options]}" if opts[:signing_options]
+      else
+        signing = ''
+      end # if opts[:signing_identity]
+
+      ### first, run 'analyze' to get a 'component plist' in which we can change some settings
+      ### for any bundles in the root (bundles like .apps, frameworks, plugins, etc..)
+      ###
+      ### we edit the settings thus:
+      ### BundleOverwriteAction = upgrade, totally replace any version current on disk
+      ### BundleIsVersionChecked = false, allow us to install regardless of what version is currently installed
+      ### BundleIsRelocatable = false,  if there's a version of this in some other location, Do Not move this one there after installation
+      ### BundleHasStrictIdentifier = false, don't care if there's something at the install path with a different bundle id.
+      ###
+      ### In other words, just install the thing!
+      ### (see 'man pkgbuild' for more info)
+      ###
+      ###
+      comp_plist_out = Pathname.new "/tmp/#{PKG_BUNDLE_ID_PFX}-#{pkg_filename}.plist"
+      system "#{PKGBUILD} --analyze --root '#{root}' '#{comp_plist_out}'"
+      comp_plist = Plist.parse_xml comp_plist_out.read
+
+      ### if the plist is empty, there are no bundles in the pkg
+      if comp_plist[0].nil?
+        comp_plist_arg = ''
+      else
+        ### otherwise, edit the bundle dictionaries
+        comp_plist.each do |bndl|
+          bndl.delete 'ChildBundles' if bndl['ChildBundles']
+          bndl['BundleOverwriteAction'] = 'upgrade'
+          bndl['BundleIsVersionChecked'] = false
+          bndl['BundleIsRelocatable'] = false
+          bndl['BundleHasStrictIdentifier'] = false
+        end
+        ### write out the edits
+        comp_plist_out.open('w') { |f| f.write comp_plist.to_plist }
+        comp_plist_arg = "--component-plist '#{comp_plist_out}'"
+      end
+
+      ### now build the pkg
+      begin
+        it_built = system "#{PKGBUILD} --identifier '#{pkg_id}' --version '#{version}' --ownership #{pkg_ownership} --install-location / --root '#{root}' #{signing} #{comp_plist_arg} '#{pkg_out}' "
+
+        raise 'There was an error building the .pkg' unless it_built
+      ensure
+        comp_plist_out.delete if comp_plist_out.exist?
+      end
+
+      Pathname.new pkg_out
+    end # mk_dot_pkg
+
+    ###
+    ### Make a casper-happy .dmg out of a root folder, permissions are assumed to be correct.
+    ###
+    ### @param name[String] The name of the .dmg, the suffix will be added if needed
+    ###
+    ### @param root[String, Pathname]  the path to the "root folder" representing the root file system of the target install drive
+    ###
+    ### @param out_dir[String, Pathname] the folder in which the .pkg will be created. Defaults to {DEFAULT_OUT_DIR}
+    ###
+    ### @return [Pathname] the local path to the new .dmg
+    ###
+    ###
+    def self.mk_dmg(name, root, out_dir = DEFAULT_OUT_DIR)
+      dmg_filename = "#{name}.dmg"
+      dmg_vol = name
+      dmg_out = Pathname.new "#{out_dir}/#{dmg_filename}"
+      if dmg_out.exist?
+        mv_to = dmg_out.dirname + "#{dmg_out.basename}.#{Time.now.strftime('%Y%m%d%H%M%S')}"
+        dmg_out.rename mv_to
+      end # if dmg out exist
+
+      ### TODO - this may need to be sudo'd to handle proper internal permissions.
+      system "#{HDI_UTIL} create -volname '#{dmg_vol}' -scrub -srcfolder '#{root}' '#{dmg_out}'"
+
+      raise 'There was an error building the .dmg' unless $?.exitstatus.zero?
+      Pathname.new dmg_out
+    end # mk_dmg
+
+  end # module Composer
+
+end # module Jamf

data/lib/jamf/configuration.rb

@@ -0,0 +1,281 @@
+# Copyright 2019 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 Jamf
+
+  # Module Variables
+  #####################################
+
+  # Module Methods
+  #####################################
+
+  # Classes
+  #####################################
+
+
+  # A class for working with pre-defined settings & preferences for the JAMF Gem
+  #
+  # This is a singleton class, only one instance can exist at a time.
+  #
+  # When the JAMF module loads, that instance is created and stored in the constant {Jamf::CONFIG},
+  # which can then be used in applications to avoid always having to pass in server names, API user names
+  # and so on.
+  #
+  # When the Jamf::Configuration instance is created, the {GLOBAL_CONF} file (/etc/jss_gem.conf) is examined if it exists, and
+  # the items in it are loaded into the attributes.
+  #
+  # Then the user-specific {USER_CONF} file (~/.ruby-jss.conf) is examined if it exists, and any attributes defined there will
+  # override those values from the {GLOBAL_CONF}.
+  #
+  # The file format is one attribute per line, thus:
+  #   attr_name: value
+  #
+  # Lines that don't start with a known attribute name followed by a colon are ignored. If an attribute is defined
+  # more than once, the last one wins.
+  #
+  # The known attributes are:
+  # - api_server_name [String] the hostname of the JAMF API server
+  # - api_server_port [Integer] the port number for the API connection
+  # - api_ssl_version [String] the SSL version (from the open_ssl module) to use for the connection.
+  # - api_verify_cert [Boolean] if SSL is used, should the SSL certificate be verified (usually false for a self-signed cert)
+  # - api_username [String] the JAMF username for connecting to the API
+  # - api_timeout_open [Integer] the number of seconds for the open-connection timeout
+  # - api_timeout [Integer] the number of seconds for the response timeout
+  #
+  # The {APIConnection#connect} method will first use any values given as method arguments. For any not given, it will
+  # look at the Preferences instance for any values there, and if still none, will use default values or raise an exception.
+  #
+  # At any point, the attributes can read or changed using standard Ruby getter/setter methods matching the name of the attribute,
+  # e.g.
+  #   Jamf::CONFIG.api_server_name  # => 'myjss.mycompany.com'
+  #   Jamf::CONFIG.api_server_name = 'otherjss.mycompany.com'  # sets the api_server_name to a new value
+  #
+  #
+  # The current settings may be saved to the GLOBAL_CONF file, the USER_CONF file, or an arbitrary file using {#save}.
+  # The argument to {#save} should be either :user, :global, or a String or Pathname file path.
+  # NOTE: This overwrites any existing file.
+  #
+  # To re-load the settings use {#reload}. This clears the current settings, and re-reads both the global and user files.
+  # If a pathname is provided, e.g.
+  #   Jamf::CONFIG.reload '/path/to/other/file'
+  # the current settings are cleared and reloaded from that other file.
+  #
+  # To view the current settings, use {#print}.
+  #
+  # @note Passwords are not saved in prefs files. Your application will have to acquire them using the :prompt or :stdin options to
+  #   {APIConnection#connect}, or by custom means.
+  #
+  class Configuration
+
+    include Singleton
+
+    # Class Constants
+    #####################################
+
+    # The filename for storing the config, globally or user-level.
+    # The first matching file is used - the array provides
+    # backward compatibility with earlier versions.
+    # Saving will always happen to the first filename
+    CONF_FILENAME = 'ruby-jss.conf'.freeze
+
+    # The Pathname to the machine-wide preferences
+    GLOBAL_CONF_FILE = Pathname.new "/etc/#{CONF_FILENAME}"
+
+    # The Pathname to the user-specific preferences plist
+    USER_CONF_FILE = ENV['HOME'] ? Pathname.new("~/.#{CONF_FILENAME}").expand_path : nil
+
+    # The attribute keys we maintain, and the type they should be stored as
+    CONF_KEYS = {
+      api_server_name: :to_s,
+      api_server_port: :to_i,
+      api_ssl_version: :to_s,
+      api_verify_cert: :j_to_bool,
+      api_username: :to_s,
+      api_timeout_open: :to_i,
+      api_timeout: :to_i,
+      db_server_name: :to_s,
+      db_server_port: :to_i,
+      db_server_socket: :to_s,
+      db_username: :to_s,
+      db_name: :to_s,
+      db_connect_timeout: :to_i,
+      db_read_timeout: :to_i,
+      db_write_timeout: :to_i
+    }.freeze
+
+    # Attributes
+    #####################################
+
+    # automatically create accessors for all the CONF_KEYS
+    CONF_KEYS.keys.each { |k| attr_accessor k }
+
+    # Constructor
+    #####################################
+
+
+    # Initialize!
+    #
+    def initialize
+      read_global
+      read_user
+    end
+
+    # Public Instance Methods
+    #####################################
+
+
+    # Clear all values
+    #
+    # @return [void]
+    #
+    def clear_all
+      CONF_KEYS.keys.each { |k| send "#{k}=".to_sym, nil }
+    end
+
+    # (Re)read the global prefs, if it exists.
+    #
+    # @return [void]
+    #
+    def read_global
+      read GLOBAL_CONF_FILE if GLOBAL_CONF_FILE.file? && GLOBAL_CONF_FILE.readable?
+    end
+
+    # (Re)read the user prefs, if it exists.
+    #
+    # @return [void]
+    #
+    def read_user
+      read USER_CONF_FILE if USER_CONF_FILE.file? && USER_CONF_FILE.readable?
+    end
+
+    # Clear the settings and reload the prefs files, or another file if provided
+    #
+    # @param file[String,Pathname] a non-standard prefs file to load
+    #
+    # @return [void]
+    #
+    def reload(file = nil)
+      clear_all
+      if file
+        read file
+        return true
+      end
+      read_global
+      read_user
+      true
+    end
+
+    # Save the prefs into a file
+    #
+    # @param file[Symbol,String,Pathname] either :user, :global, or an arbitrary file to save.
+    #
+    # @return [void]
+    #
+    def save(file)
+      path =
+        case file
+          when :global then GLOBAL_CONF_FILE
+          when :user then USER_CONF_FILE
+          else Pathname.new(file)
+        end
+
+      raise Jamf::MissingDataError, "No HOME environment variable, can't write to user conf file." if path.nil?
+
+      # file already exists? read it in and update the values.
+      if path.readable?
+        data = path.read
+
+        # go thru the known attributes/keys
+        CONF_KEYS.keys.sort.each do |k|
+          # if the key exists, update it.
+          if data =~ /^#{k}:/
+            data.sub!(/^#{k}:.*$/, "#{k}: #{send k}")
+
+          # if not, add it to the end unless it's nil
+          else
+            data += "\n#{k}: #{send k}" unless send(k).nil?
+          end # if data =~ /^#{k}:/
+        end # each do |k|
+
+      else # not readable, make a new file
+        data = ''
+        CONF_KEYS.keys.sort.each do |k|
+          data << "#{k}: #{send k}\n" unless send(k).nil?
+        end
+      end # if path readable
+
+      # make sure we end with a newline, the save it.
+      data << "\n" unless data.end_with?("\n")
+      path.j_save data
+    end # read file
+
+    # Print out the current settings to stdout
+    #
+    # @return [void]
+    #
+    def print
+      CONF_KEYS.keys.sort.each { |k| puts "#{k}: #{send k}" }
+    end
+
+    # Private Instance Methods
+    #####################################
+    private
+
+    # Read in any prefs file
+    #
+    # @param file[String,Pathname] the file to read
+    #
+    # @return [void]
+    #
+    def read(file)
+      Pathname.new(file).read.each_line do |line|
+        # skip blank lines and those starting with #
+        next if line =~ /^\s*(#|$)/
+
+        line.strip =~ /^(\w+?):\s*(\S.*)$/
+        next unless Regexp.last_match(1)
+
+        attr = Regexp.last_match(1).to_sym
+        setter = "#{attr}=".to_sym
+        value = Regexp.last_match(2).strip
+
+        next unless CONF_KEYS.key?(attr)
+
+        if value
+          # convert the value to the correct class
+          value = value.send(CONF_KEYS[attr])
+        end
+        send(setter, value)
+        # if
+      end # do line
+    end # read file
+
+  end # class Config
+
+  def self.config
+    Jamf::Configuration.instance
+  end
+
+end # module