Module: Jamf

Defined in:
lib/jamf.rb,
lib/jamf/client.rb,
lib/jamf/utility.rb,
lib/jamf/version.rb,
lib/jamf/composer.rb,
lib/jamf/validate.rb,
lib/jamf/exceptions.rb,
lib/jamf/configuration.rb,
lib/jamf/api/connection.rb,
lib/jamf/api/mixins/lockable.rb,
lib/jamf/api/mixins/pageable.rb,
lib/jamf/api/mixins/sortable.rb,
lib/jamf/api/connection/token.rb,
lib/jamf/api/mixins/immutable.rb,
lib/jamf/api/mixins/base_class.rb,
lib/jamf/api/mixins/change_log.rb,
lib/jamf/api/mixins/extendable.rb,
lib/jamf/api/mixins/filterable.rb,
lib/jamf/api/mixins/searchable.rb,
lib/jamf/api/mixins/uncreatable.rb,
lib/jamf/api/mixins/undeletable.rb,
lib/jamf/api/json_objects/locale.rb,
lib/jamf/api/connection/api_error.rb,
lib/jamf/api/json_objects/country.rb,
lib/jamf/api/base_classes/prestage.rb,
lib/jamf/api/base_classes/resource.rb,
lib/jamf/api/mixins/bulk_deletable.rb,
lib/jamf/api/json_objects/time_zone.rb,
lib/jamf/api/base_classes/json_object.rb,
lib/jamf/api/attribute_classes/timestamp.rb,
lib/jamf/api/json_objects/prestage_scope.rb,
lib/jamf/api/attribute_classes/ip_address.rb,
lib/jamf/api/json_objects/change_log_entry.rb,
lib/jamf/api/json_objects/md_prestage_name.rb,
lib/jamf/api/json_objects/md_prestage_names.rb,
lib/jamf/api/json_objects/prestage_location.rb,
lib/jamf/api/base_classes/singleton_resource.rb,
lib/jamf/api/connection/api_error_styleguide.rb,
lib/jamf/api/base_classes/collection_resource.rb,
lib/jamf/api/json_objects/prestage_assignment.rb,
lib/jamf/api/json_objects/prestage_sync_status.rb,
lib/jamf/api/json_objects/device_enrollment_device.rb,
lib/jamf/api/json_objects/prestage_purchasing_data.rb,
lib/jamf/api/resources/collection_resources/script.rb,
lib/jamf/api/resources/singleton_resources/locales.rb,
lib/jamf/api/resources/collection_resources/building.rb,
lib/jamf/api/resources/collection_resources/category.rb,
lib/jamf/api/resources/singleton_resources/time_zones.rb,
lib/jamf/api/json_objects/md_prestage_skip_setup_items.rb,
lib/jamf/api/resources/collection_resources/department.rb,
lib/jamf/api/json_objects/device_enrollment_sync_status.rb,
lib/jamf/api/json_objects/device_enrollment_device_sync_state.rb,
lib/jamf/api/resources/collection_resources/computer_prestage.rb,
lib/jamf/api/resources/collection_resources/device_enrollment.rb,
lib/jamf/api/json_objects/inventory_preload_extension_attribute.rb,
lib/jamf/api/resources/collection_resources/mobile_device_prestage.rb,
lib/jamf/api/resources/singleton_resources/app_store_country_codes.rb,
lib/jamf/api/resources/collection_resources/inventory_preload_record.rb

Overview

The Module

Defined Under Namespace

Modules: BaseClass, BulkDeletable, ChangeLog, Composer, Extendable, Filterable, Immutable, Lockable, Pageable, Searchable, Sortable, UnCreatable, UnDeletable, Validate Classes: APIError, APIErrorDetail, APIRequestError, AlreadyExistsError, AppStoreCountryCodes, AuthenticationError, BadRequestError, Building, Category, ChangeLogEntry, Client, CollectionResource, ComputerPrestage, Configuration, ConflictError, Connection, Country, Department, DeviceEnrollment, DeviceEnrollmentDevice, DeviceEnrollmentDeviceSyncState, DeviceEnrollmentSyncStatus, FileServiceError, IPAddress, InvalidConnectionError, InvalidDataError, InvalidTokenError, InventoryPreloadExtensionAttribute, InventoryPreloadRecord, JSONObject, Locale, Locales, MissingDataError, MobileDevicePrestage, MobileDevicePrestageName, MobileDevicePrestageNames, MobileDevicePrestageSkipSetupItems, NoSuchItemError, Prestage, PrestageAssignment, PrestageLocation, PrestagePurchasingData, PrestageScope, PrestageSyncStatus, Resource, Script, SingletonResource, TimeZone, TimeZones, TimeoutError, Timestamp, UnmanagedError, UnsupportedError, VersionLockError

Constant Summary collapse

MINIMUM_RUBY_VERSION =

The minimum Ruby version that works with this gem 2.3 allows us to start using some nice features like the safe-navigation operator and Array#dig & Hash#dig, and such.

For a list of features, see github.com/ruby/ruby/blob/v2_3_0/NEWS and nithinbekal.com/posts/ruby-2-3-features/

'2.3'.freeze
BLANK =

These Utility constants are useful all over the place. Many of them are commonly used Strings.

''.freeze
UNDERSCORE = 
'_'.freeze
VERSION =

The version of the Jamf module

'0.0.8'.freeze

Class Method Summary collapse

Class Method Details

.api_object_class(name) ⇒ Class

TODO: Move to APIObject

Given a name, singular or plural, of a Jamf::APIObject subclass as a String or Symbol (e.g. :computer/‘computers’), return the class itself (e.g. Jamf::Computer) The available names are the RSRC_LIST_KEY and RSRC_OBJECT_KEY values for each APIObject subclass.

Parameters:

  • name (String, Symbol) —

    The name of a Jamf::APIObject subclass, singluar or plural

Returns:

  • (Class) —

    The class

Raises:



302
303
304
305
306
 
# File 'lib/jamf/utility.rb', line 302

def self.api_object_class(name)
  klass = api_object_names[name.downcase.to_sym]
  raise Jamf::InvalidDataError, "Unknown API Object Class: #{name}" unless klass
  klass
end

.api_object_names ⇒ Hash

TODO: Move to APIObject

APIObject subclasses have singular names, and are, of course capitalized, e.g. ‘Computer’ But we often want to refer to them in the plural, or lowercase, e.g. ‘computers’ This method returns a Hash of the RSRC_LIST_KEY (a plural symbol) and the RSRC_OBJECT_KEY (a singular symbol) of each APIObject subclass, keyed to the class itself, such that both :computer and :computers are keys for Jamf::Computer and both :policy and :policies are keys for Jamf::Policy, and so on.

Returns:

  • (Hash) —

    APIObject subclass names to Classes



322
323
324
325
326
327
328
329
330
331
332
333
 
# File 'lib/jamf/utility.rb', line 322

def self.api_object_names
  return @api_object_names if @api_object_names
  @api_object_names ||= {}
  JSS.constants.each do |const|
    klass = JSS.const_get const
    next unless klass.is_a? Class
    next unless klass.ancestors.include? Jamf::APIObject
    @api_object_names[klass.const_get(:RSRC_LIST_KEY).to_sym] = klass if klass.constants.include? :RSRC_LIST_KEY
    @api_object_names[klass.const_get(:RSRC_OBJECT_KEY).to_sym] = klass if klass.constants.include? :RSRC_OBJECT_KEY
  end
  @api_object_names
end

.cnx ⇒ Jamf::Connection

Returns the active connection.

Returns:



825
826
827
 
# File 'lib/jamf/api/connection.rb', line 825

def self.cnx
  @active_connection ||= Connection.new do_not_connect: true
end

.cnx=(connection) ⇒ APIConnection

Switch the connection used for all API interactions to the one provided. See APIConnection for details and examples of using multiple connections

Parameters:

  • connection (APIConnection) —

    The APIConnection to use for future API calls. If omitted, use the default connection created when ruby-jss was loaded (which may or may not yet be connected)

Returns:

  • (APIConnection) —

    The connection now being used.



854
855
856
857
858
 
# File 'lib/jamf/api/connection.rb', line 854

def self.cnx=(connection)
  raise 'API connections must be instances of Jamf::Connection' unless connection.is_a? Jamf::Connection

  @active_connection = connection
end

.config ⇒ Object

class Config



275
276
277
 
# File 'lib/jamf/configuration.rb', line 275

def self.config
  Jamf::Configuration.instance
end

.connect(url = nil, **params) ⇒ APIConnection

Create a new Connection object and use it as the active_connection, replacing the current active_connection. If connection options are provided, they are passed to the connect method immediately, otherwise Jamf.cnx.connect must be called before attemting to use the connection.

Parameters:

Returns:

  • (APIConnection) —

    the new, active connection



839
840
841
842
 
# File 'lib/jamf/api/connection.rb', line 839

def self.connect(url = nil, **params)
  @active_connection = Connection.new url, params
  @active_connection.to_s
end

.devmode(setting) ⇒ Boolean

un/set devmode mode. Useful when coding - methods can call JSS.devmode? and then e.g. spit out something instead of performing some action.

Parameters:

  • Set (Symbol) —

    devmode :on or :off

Returns:

  • (Boolean) —

    The new state of devmode



439
440
441
 
# File 'lib/jamf/utility.rb', line 439

def self.devmode(setting)
  @devmode = setting == :on
end

.devmode? ⇒ Boolean

is devmode currently on?

Returns:

  • (Boolean) 


447
448
449
 
# File 'lib/jamf/utility.rb', line 447

def self.devmode?
  @devmode
end

.disconnect ⇒ Object 



860
861
862
 
# File 'lib/jamf/api/connection.rb', line 860

def self.disconnect
  @active_connection.disconnect if @active_connection
end

.epoch_to_time(epoch) ⇒ Time?

TODO: Sill needed in Jamf API?

Converts JSS epoch (unix epoch + milliseconds) to a Ruby Time object

Parameters:

  • epoch (String, Integer, nil)

Returns:

  • (Time, nil) —

    nil is returned if epoch is nil, 0 or an empty String.



282
283
284
285
 
# File 'lib/jamf/utility.rb', line 282

def self.epoch_to_time(epoch)
  return nil if NIL_DATES.include? epoch
  Time.at(epoch.to_i / 1000.0)
end

.expand_min_os(min_os) ⇒ Array

Converts an OS Version into an Array of higher OS versions.

It’s unlikely that this library will still be in use as-is by the release of OS X 10.30.20. Hopefully well before then JAMF will implement a “minimum OS” in the JSS itself.

Examples:

JSS.expand_min_os ">=10.6.7" # => returns this array
 # ["10.6.7",
 #  "10.6.8",
 #  "10.6.9",
 #   ...
 #  "10.6.20",
 #  "10.7.x",
 #  "10.8.x",
 #  ...
 #  "10.30.x"]

Parameters:

  • min_os (String) —

    the mimimum OS version to expand, e.g. “>=10.6.7” or “10.6.7”

Returns:

  • (Array) —

    Nearly all potential OS versions from the minimum to 10.19.x.



67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
 
# File 'lib/jamf/utility.rb', line 67

def self.expand_min_os(min_os)
  min_os = min_os.delete '>='

  # split the version into major, minor and maintenance release numbers
  (maj, min, maint) = min_os.split('.')
  maint = 'x' if maint.nil? || maint == '0'

  # if the maint release number is an "x" just start the list of OK OS's with it
  if maint == 'x'
    ok_oses = [maj + '.' + min.to_s + '.x']

  # otherwise, start with it and explicitly add all maint releases up to 20
  # (and hope apple doesn't do more than 20 maint releases for an OS)
  else
    ok_oses = []
    (maint.to_i..20).each do |m|
      ok_oses << maj + '.' + min + '.' + m.to_s
    end # each m
  end

  # now account for all OS X versions starting with 10.
  # up to at least 10.30.x
  ((min.to_i + 1)..30).each do |v|
    ok_oses << maj + '.' + v.to_s + '.x'
  end # each v
  ok_oses
end

.humanize_secs(secs) ⇒ Object

Very handy! lifted from stackoverflow.com/questions/4136248/how-to-generate-a-human-readable-time-range-using-ruby-on-rails



421
422
423
424
425
426
427
428
429
 
# File 'lib/jamf/utility.rb', line 421

def self.humanize_secs(secs)
  [[60, :second], [60, :minute], [24, :hour], [7, :day], [52.179, :week], [1_000_000, :year]].map do |count, name|
    next unless secs > 0

    secs, n = secs.divmod(count)
    n = n.to_i
    "#{n} #{n == 1 ? name : (name.to_s + 's')}"
  end.compact.reverse.join(' ')
end

.os_ok?(requirement, os_to_check = nil) ⇒ Boolean

Scripts and packages can have OS limitations. This method tests a given OS, against a requirement list to see if the requirement is met.

Parameters:

  • requirement (String, Array) —

    The os requirement list, a comma-seprated string or array of strings of allows OSes. e.g. 10.7, 10.8.5 or 10.9.x

  • processor (String) —

    the os to check, defaults to the os of the current machine.

Returns:

  • (Boolean) —

    can this pkg be installed with the processor given?



128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
 
# File 'lib/jamf/utility.rb', line 128

def self.os_ok?(requirement, os_to_check = nil)
  return true if requirement.to_s =~ /none/i
  return true if requirement.to_s == 'n'
  requirement = JSS.to_s_and_a(requirement)[:arrayform]
  return true if requirement.empty?

  os_to_check ||= `/usr/bin/sw_vers -productVersion`.chomp

  # convert the requirement array into an array of regexps.
  # examples:
  #   "10.8.5" becomes  /^10\.8\.5$/
  #   "10.8" becomes /^10.8(.0)?$/
  #   "10.8.x" /^10\.8\.?\d*$/
  req_regexps = requirement.map do |r|
    if r.end_with?('.x')
      /^#{r.chomp('.x').gsub('.', '\.')}(\.?\d*)*$/

    elsif r =~ /^\d+\.\d+$/
      /^#{r.gsub('.', '\.')}(.0)?$/

    else
      /^#{r.gsub('.', '\.')}$/
    end
  end

  req_regexps.each { |re| return true if os_to_check =~ re }
  false
end

.parse_jss_version(version) ⇒ Hash{Symbol => String, Gem::Version}

TODO: Update or remove for Jamf API Parse a JSS Version number into something comparable.

This method returns a Hash with these keys:

  • :major => the major version, Integer

  • :minor => the minor version, Integor

  • :maint => the revision, Integer (also available as :patch and :revision)

  • :build => the revision, String

  • :version => a Gem::Version object built from :major, :minor, :revision which can be easily compared with other Gem::Version objects.

NOTE: the :version value ignores build numbers, so comparisons only compare major.minor.maint

Parameters:

  • version (String) —

    a JSS version number from the API

Returns:

  • (Hash{Symbol => String, Gem::Version}) —

    the parsed version data.

Raises:



353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
 
# File 'lib/jamf/utility.rb', line 353

def self.parse_jss_version(version)
  major, second_part, *_rest = version.split('.')
  raise Jamf::InvalidDataError, 'JSS Versions must start with "x.x" where x is one or more digits' unless major =~ /\d$/ && second_part =~ /^\d/

  release, build = version.split(/-/)

  major, minor, revision = release.split '.'
  minor ||= 0
  revision ||= 0

  {
    major: major.to_i,
    minor:  minor.to_i,
    revision:  revision.to_i,
    maint:  revision.to_i,
    patch:  revision.to_i,
    build:  build,
    version: Gem::Version.new("#{major}.#{minor}.#{revision}")
  }
end

.parse_plist(plist, symbol_keys: false) ⇒ Object

Parse a plist into a Ruby data structure. The plist parameter may be a String containing an XML plist, or a path to a plist file, or it may be a Pathname object pointing to a plist file. The plist files may be XML or binary.

Parameters:

  • plist (Pathname, String) —

    the plist XML, or the path to a plist file

  • symbol_keys (Boolean) (defaults to: false) —

    should any Hash keys in the result be converted into Symbols rather than remain as Strings?

Returns:

  • (Object) —

    the parsed plist as a ruby hash,array, etc.



202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
 
# File 'lib/jamf/utility.rb', line 202

def self.parse_plist(plist, symbol_keys: false)
  require 'cfpropertylist'

  # did we get a string of xml, or a string pathname?
  case plist
  when String
    return CFPropertyList.native_types(CFPropertyList::List.new(data: plist).value, symbol_keys) if plist.include? '</plist>'

    plist = Pathname.new plist
  when Pathname
    true
  else
    raise ArgumentError, 'Argument must be a path (as a Pathname or String) or a String of XML'
  end # case plist

  # if we're here, its a Pathname
  raise JSS::MissingDataError, "No such file: #{plist}" unless plist.file?

  CFPropertyList.native_types(CFPropertyList::List.new(file: plist).value, symbol_keys)
end

.parse_time(a_datetime) ⇒ Time?

TODO: Sill needed in Jamf API?

Converts anything that responds to #to_s to a Time, or nil

Return nil if the item is nil, 0 or an empty String.

Otherwise the item converted to a string, and parsed with DateTime.parse. It is then examined to see if it has a UTC offset. If not, the local offset is applied, then the DateTime is converted to a Time.

Parameters:

  • a_datetime (#to_s) —

    The thing to convert to a time.

Returns:

  • (Time, nil) —

    nil is returned if a_datetime is nil, 0 or an empty String.



258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
 
# File 'lib/jamf/utility.rb', line 258

def self.parse_time(a_datetime)
  return nil if NIL_DATES.include? a_datetime

  the_dt = DateTime.parse(a_datetime.to_s)

  # The microseconds in DateTimes are stored as a fraction of a day.
  # Convert them to an integer of microseconds
  usec = (the_dt.sec_fraction * 60 * 60 * 24 * (10**6)).to_i

  # if the UTC offset of the datetime is zero, make a new one with the correct local offset
  # (which might also be zero if we happen to be in GMT)
  the_dt = DateTime.new(the_dt.year, the_dt.month, the_dt.day, the_dt.hour, the_dt.min, the_dt.sec, Jamf::TIME_ZONE_OFFSET) if the_dt.offset.zero?
  # now convert it to a Time and return it
  Time.at the_dt.strftime('%s').to_i, usec
end

.processor_ok?(requirement, processor = nil) ⇒ Boolean

Scripts and packages can have processor limitations. This method tests a given processor, against a requirement to see if the requirement is met.

Parameters:

  • requirement (String) —

    The processor requirement. either ‘ppc’, ‘x86’, or some variation on “none”, nil, or empty

  • processor (String) (defaults to: nil) —

    the processor to check, defaults to the processor of the current machine. Any flavor of intel

    is (i486, i386, x86-64, etc) is treated as "x86"

Returns:

  • (Boolean) —

    can this pkg be installed with the processor given?



109
110
111
112
113
 
# File 'lib/jamf/utility.rb', line 109

def self.processor_ok?(requirement, processor = nil)
  return true if requirement.to_s.empty? || requirement =~ /none/i
  processor ||= `/usr/bin/uname -p`
  requirement == (processor.to_s.include?('86') ? 'x86' : 'ppc')
end

.prompt_for_password(message) ⇒ String

Prompt for a password in a terminal.

Parameters:

  • message (String) —

    the prompt message to display

Returns:

  • (String) —

    the text typed by the user



404
405
406
407
408
409
410
411
412
413
414
415
 
# File 'lib/jamf/utility.rb', line 404

def self.prompt_for_password(message)
  begin
    $stdin.reopen '/dev/tty' unless $stdin.tty?
    $stderr.print "#{message} "
    system '/bin/stty -echo'
    pw = $stdin.gets.chomp("\n")
    puts
  ensure
    system '/bin/stty echo'
  end # begin
  pw
end

.stdin(line = 0) ⇒ String?

Retrive one or all lines from whatever was piped to standard input.

Standard input is read completely the first time this method is called and the lines are stored as an Array in the module var @stdin_lines

Parameters:

  • line (Integer) (defaults to: 0) —

    which line of stdin is being retrieved. The default is zero (0) which returns all of stdin as a single string.

Returns:

  • (String, nil) —

    the requested ling of stdin, or nil if it doesn’t exist.



390
391
392
393
394
395
396
 
# File 'lib/jamf/utility.rb', line 390

def self.stdin(line = 0)
  @stdin_lines ||= ($stdin.tty? ? [] : $stdin.read.lines.map { |l| l.chomp("\n") })

  return @stdin_lines.join("\n") if line <= 0
  idx = line - 1
  @stdin_lines[idx]
end

.superuser? ⇒ Boolean

Returns is this code running as root?.

Returns:

  • (Boolean) —

    is this code running as root?



376
377
378
 
# File 'lib/jamf/utility.rb', line 376

def self.superuser?
  Process.euid.zero?
end

.to_s_and_a(somedata) ⇒ Hash{:stringform => String, :arrayform => Array}

Given a list of data as a comma-separated string, or an Array of strings, return a Hash with both versions.

Some parts of the JSS require lists as comma-separated strings, while often those data are easier work with as arrays. This method is a handy way to get either form when given either form.

Examples:

JSS.to_s_and_a "foo, bar, baz" # Hash => {:stringform => "foo, bar, baz", :arrayform => ["foo", "bar", "baz"]}

JSS.to_s_and_a ["foo", "bar", "baz"] # Hash => {:stringform => "foo, bar, baz", :arrayform => ["foo", "bar", "baz"]}

Parameters:

  • somedata (String, Array) —

    the data to parse, of either class,

Returns:

  • (Hash{:stringform => String, :arrayform => Array}) —

    the data as both comma-separated String and Array



173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
 
# File 'lib/jamf/utility.rb', line 173

def self.to_s_and_a(somedata)
  case somedata
  when nil
    valstr = ''
    valarr = []
  when String
    valstr = somedata
    valarr = somedata.split(/,\s*/)
  when Array
    valstr = somedata.join ', '
    valarr = somedata
  else
    raise Jamf::InvalidDataError, 'Input must be a comma-separated String or an Array of Strings'
  end # case
  { stringform: valstr, arrayform: valarr }
end

.xml_plist_from(data) ⇒ String

Convert any ruby data to an XML plist.

NOTE: Binary data is tricky. Easiest way is to pass in a Pathname or IO object (anything that responds to ‘read` and returns a bytestring) and then the CFPropertyList.guess method will read it and convert it to a Plist <data> element with base64 encoded data. For more info, see CFPropertyList.guess

Parameters:

  • data (Object) —

    the data to be converted, usually a Hash

Returns:

  • (String) —

    the object converted into an XML plist



237
238
239
240
241
242
 
# File 'lib/jamf/utility.rb', line 237

def self.xml_plist_from(data)
  require 'cfpropertylist'
  plist = CFPropertyList::List.new
  plist.value = CFPropertyList.guess(data, convert_unknown_to_string: true)
  plist.to_str(CFPropertyList::List::FORMAT_XML)
end