Class: JSS::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/jss-api/client.rb,
lib/jss-api.rb

Overview

This class represents a Casper/JSS Client computer, on which this code is running.

Since the class represents the current machine, there’s no need to make an instance of it, all methods are class methods.

At the moment, only Macintosh computers are supported.

Constant Summary collapse

ORIG_JAMF_BINARY =

The Pathname to the jamf binary executable As of El Capitan (OS X 10.11) the location has moved.

Pathname.new "/usr/sbin/jamf"
ELCAP_JAMF_BINARY = 
Pathname.new "/usr/local/jamf/bin/jamf"
JAMF_BINARY = 
ELCAP_JAMF_BINARY.executable? ? ELCAP_JAMF_BINARY : ORIG_JAMF_BINARY
JAMF_HELPER =

The Pathname to the jamfHelper executable

Pathname.new "/Library/Application Support/JAMF/bin/jamfHelper.app/Contents/MacOS/jamfHelper"
JAMF_HELPER_WINDOW_TYPES =

The window_type options for jamfHelper

{
  :hud => 'hud',
  :utility => 'utility',
  :util => 'utility',
  :full_screen => 'fs',
  :fs => 'fs'
}
JAMF_HELPER_WINDOW_POSITIONS =

The possible window positions for jamfHelper

[nil, :ul, :ll, :ur, :lr]
JAMF_HELPER_BUTTONS =

The available buttons in jamfHelper

[1,2]
JAMF_HELPER_ALIGNMENTS =

The possible alignment positions in jamfHelper

[:right, :left, :center, :justified, :natural]
JAMF_PLIST =

The Pathname to the preferences plist used by the jamf binary

Pathname.new "/Library/Preferences/com.jamfsoftware.jamf.plist"
JAMF_SUPPORT_FOLDER =

The Pathname to the JAMF support folder

Pathname.new "/Library/Application Support/JAMF"
RECEIPTS_FOLDER =

The JAMF receipts folder, where package installs are tracked.

JAMF_SUPPORT_FOLDER + "Receipts"
DOWNLOADS_FOLDER =

The JAMF downloads folder

JAMF_SUPPORT_FOLDER + "Downloads"
ROOTLESS_JAMF_COMMANDS =

These jamf commands don’t need root privs (most do)

[
:about,
:checkJSSConnection,
:getARDFields,
:getComputerName,
:help,
:listUsers,
:version ]

Class Method Summary collapse

Class Method Details

.hardware_data ⇒ Hash

Returns the HardwareDataType data from the system_profiler command.

Returns:

  • (Hash) —

    the HardwareDataType data from the system_profiler command



245
246
247
248
 
# File 'lib/jss-api/client.rb', line 245

def self.hardware_data
  raw = `/usr/sbin/system_profiler SPHardwareDataType -xml 2>/dev/null`
  Plist.parse_xml(raw)[0]["_items"][0]
end

.installed? ⇒ Boolean

Returns is the jamf binary installed?.

Returns:

  • (Boolean) —

    is the jamf binary installed?



143
144
145
 
# File 'lib/jss-api/client.rb', line 143

def self.installed?
  JAMF_BINARY.executable?
end

.jamf_helper(window_type = :hud, opts = {}) ⇒ Integer

Returns the exit status of the jamfHelper command. See above.

Parameters:

  • opts (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (opts):

  • :countdown (any value) —

    Displays a string notifying the user when the window will time out

  • :align_countdown (Symbol) —

    one of [:right, :left, :center, :justified, :natural] Aligns the countdown to the specified alignment

  • :lock_hud (any value) —

    Removes the ability to exit the HUD by selecting the close button

Returns:

  • (Integer) —

    the exit status of the jamfHelper command. See above.

Raises:



405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
 
# File 'lib/jss-api/client.rb', line 405

def self.jamf_helper(window_type = :hud, opts = {})

  raise JSS::UnmanagedError, "The jamfHelper app is not installed properly on this computer." unless JAMF_HELPER.executable?

  unless JAMF_HELPER_WINDOW_TYPES.include? window_type
    raise JSS::InvalidDataError, "The first parameter must be a window type, one of :#{JAMF_HELPER_WINDOW_TYPES.keys.join(', :')}."
  end

  # start building the arg array

  args = ["-startlaunchd", "-windowType", JAMF_HELPER_WINDOW_TYPES[window_type]]

  opts.keys.each do |opt|
    case opt
      when :window_position
        raise JSS::InvalidDataError, ":window_position must be one of :#{JAMF_HELPER_WINDOW_POSITIONS.join(', :')}." unless JAMF_HELPER_WINDOW_POSITIONS.include? opts[opt].to_sym
        args << "-windowPosition"
        args << opts[opt].to_s

      when :title
        args << "-title"
        args << opts[opt].to_s

      when :heading
        args << "-heading"
        args << opts[opt].to_s

      when :align_heading
        raise JSS::InvalidDataError, ":align_heading must be one of :#{JAMF_HELPER_ALIGNMENTS.join(', :')}." unless JAMF_HELPER_ALIGNMENTS.include? opts[opt].to_sym
        args << "-alignHeading"
        args << opts[opt].to_s

      when :description
        args << "-description"
        args << opts[opt].to_s

      when :align_description
        raise JSS::InvalidDataError, ":align_description must be one of :#{JAMF_HELPER_ALIGNMENTS.join(', :')}." unless JAMF_HELPER_ALIGNMENTS.include? opts[opt].to_sym
        args << "-alignDescription"
        args << opts[opt].to_s

      when :icon
        args << "-icon"
        args << opts[opt].to_s

      when :icon_size
        args << "-iconSize"
        args << opts[opt].to_s

      when :full_screen_icon
        args << "-fullScreenIcon"

      when :button1
        args << "-button1"
        args << opts[opt].to_s

      when :button2
        args << "-button2"
        args << opts[opt].to_s

      when :default_button
        raise JSS::InvalidDataError, ":default_button must be one of #{JAMF_HELPER_BUTTONS.join(', ')}." unless JAMF_HELPER_BUTTONS.include? opts[opt]
        args << "-defaultButton"
        args << opts[opt].to_s

      when :cancel_button
        raise JSS::InvalidDataError, ":cancel_button must be one of #{JAMF_HELPER_BUTTONS.join(', ')}." unless JAMF_HELPER_BUTTONS.include? opts[opt]
        args << "-cancelButton"
        args << opts[opt].to_s

      when :timeout
        args << "-timeout"
        args << opts[opt].to_s

      when :show_delay_options
        args << "-showDelayOptions"
        args << JSS.to_s_and_a(opts[opt])[:arrayform].join(', ')

      when :countdown
        args << "-countdown"

      when :align_countdown
        raise JSS::InvalidDataError, ":align_countdown must be one of :#{JAMF_HELPER_ALIGNMENTS.join(', :')}." unless JAMF_HELPER_ALIGNMENTS.include? opts[opt].to_sym
        args << "-alignCountdown"
        args << opts[opt].to_s

      when :lock_hud
        args << " -lockHUD "
    end # case opt
  end # each do opt

  system JAMF_HELPER.to_s, *args
  return $?.exitstatus

end

.jamf_plist ⇒ Hash

Returns the parsed contents of the JAMF_PLIST if it exists, an empty hash if not.

Returns:

  • (Hash) —

    the parsed contents of the JAMF_PLIST if it exists, an empty hash if not



194
195
196
197
 
# File 'lib/jss-api/client.rb', line 194

def self.jamf_plist
  return {} unless JAMF_PLIST.file?
  Plist.parse_xml `/usr/libexec/PlistBuddy -x -c print #{Shellwords.escape JSS::Client::JAMF_PLIST.to_s}`
end

.jamf_version ⇒ String?

Returns the version of the jamf binary installed on this client, nil if not installed.

Returns:

  • (String, nil) —

    the version of the jamf binary installed on this client, nil if not installed



150
151
152
 
# File 'lib/jss-api/client.rb', line 150

def self.jamf_version
  self.installed? ?  self.run_jamf(:version).chomp.split('=')[1] : nil
end

.jss_available? ⇒ Boolean

Returns is the JSS available now?.

Returns:

  • (Boolean) —

    is the JSS available now?



211
212
213
214
 
# File 'lib/jss-api/client.rb', line 211

def self.jss_available?
  output = run_jamf :checkJSSConnection, "-retry 1"
  $?.exitstatus == 0
end

.jss_port ⇒ Integer

Returns the port to the JSS for this client.

Returns:

  • (Integer) —

    the port to the JSS for this client



186
187
188
189
 
# File 'lib/jss-api/client.rb', line 186

def self.jss_port
  self.jss_url
  @port  ? @port.to_i : 80
end

.jss_protocol ⇒ String

Returns the protocol to the JSS for this client, “http” or “https”.

Returns:

  • (String) —

    the protocol to the JSS for this client, “http” or “https”



178
179
180
181
 
# File 'lib/jss-api/client.rb', line 178

def self.jss_protocol
  self.jss_url
  return @protocol
end

.jss_record ⇒ JSS::Computer

Returns The JSS record for this computer.

Returns:



220
221
222
223
224
225
226
 
# File 'lib/jss-api/client.rb', line 220

def self.jss_record
  begin
    JSS::Computer.new :udid => self.udid
  rescue JSS::NoSuchItemError
    JSS::Computer.new :serial_number => self.serial_number
  end
end

.jss_server ⇒ String

Returns the JSS server for this client.

Returns:

  • (String) —

    the JSS server for this client



170
171
172
173
 
# File 'lib/jss-api/client.rb', line 170

def self.jss_server
  self.jss_url
  return @server
end

.jss_url ⇒ String

Returns the url to the JSS for this client.

Returns:

  • (String) —

    the url to the JSS for this client



157
158
159
160
161
162
163
164
165
 
# File 'lib/jss-api/client.rb', line 157

def self.jss_url
  @url = self.jamf_plist['jss_url']
  return nil if @url.nil?
  @url =~ %r{(https?)://(.+):(\d+)/}
  @protocol = $1
  @server = $2
  @port = $3
  return @url
end

.my_ip_address ⇒ String

Get the current IP address as a String.

This handy code doesn’t acutally make a UDP connection, it just starts to set up the connection, then uses that to get the local IP.

Lifted gratefully from coderrr.wordpress.com/2008/05/28/get-your-local-ip-address/

Returns:

  • (String) —

    the current IP address.



125
126
127
128
129
130
131
132
133
134
135
136
 
# File 'lib/jss-api/client.rb', line 125

def self.my_ip_address
  ### turn off reverse DNS resolution temporarily
  ### @note the 'socket' library has already been required by 'rest-client'
  orig, Socket.do_not_reverse_lookup = Socket.do_not_reverse_lookup, true

  UDPSocket.open do |s|
    s.connect '192.168.0.0', 1
    s.addr.last
  end
ensure
  Socket.do_not_reverse_lookup = orig
end

.receipts ⇒ Array<Pathname>

Returns an array of Pathnames for all regular files in the jamf receipts folder.

Returns:

  • (Array<Pathname>) —

    an array of Pathnames for all regular files in the jamf receipts folder

Raises:



203
204
205
206
 
# File 'lib/jss-api/client.rb', line 203

def self.receipts
  raise JSS::NoSuchItemError, "The JAMF Receipts folder doesn't exist on this computer." unless RECEIPTS_FOLDER.exist?
  RECEIPTS_FOLDER.children.select{|c| c.file?}
end

.run_jamf(command, args = nil, verbose = false) ⇒ String

Note:

Most jamf commands require superuser/root privileges.

Run an arbitrary jamf binary command.

The details of the Process::Status for the jamf binary process can be captured from $? immediately after calling. (See Process::Status)

Examples:

These two are equivalent:

  JSS::Client.run_jamf "recon", "-assetTag 12345 -department 'IT Support'"

  JSS::Client.run_jamf :recon, ['-assetTag', '12345', '-department', 'IT Support'"]

Parameters:

  • command (String, Symbol) —

    the jamf binary command to run The command is the single jamf command that comes after the/usr/bin/jamf.

  • args (String, Array) (defaults to: nil) —

    the arguments passed to the jamf command. This is to be passed to Kernel.‘ (backtick), after being combined with the jamf binary and the jamf command

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

    Should the stdout & stderr of the jamf binary be sent to the current stdout in realtime, as well as returned as a string?

Returns:

  • (String) —

    the stdout & stderr of the jamf binary.

Raises:



278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
 
# File 'lib/jss-api/client.rb', line 278

def self.run_jamf(command, args = nil, verbose  = false)
  raise JSS::UnmanagedError, "The jamf binary is not installed on this computer." unless self.installed?
  raise JSS::UnsupportedError, "You must have root privileges to run that jamf binary command" unless ROOTLESS_JAMF_COMMANDS.include? command.to_sym or JSS.superuser?

  cmd = case args
    when nil
      "#{JAMF_BINARY} #{command}"
    when String
      "#{JAMF_BINARY} #{command} #{args}"
    when Array
      "#{([JAMF_BINARY.to_s, command] + args).join(' ')}"
    else
      raise JSS::InvalidDataError, "args must be a String or Array of Strings"
  end # case

  cmd += " -verbose" if verbose and (not cmd.include? " -verbose")
  puts "Running: #{cmd}" if verbose

  output = []
  IO.popen("#{cmd} 2>&1") do |proc|
    while line = proc.gets
      output << line
      puts line if verbose
    end
  end
  install_out = output.join('')
  install_out.force_encoding("UTF-8") if install_out.respond_to? :force_encoding
  return install_out
end

.serial_number ⇒ String

Returns the serial number for this computer.

Returns:

  • (String) —

    the serial number for this computer



238
239
240
 
# File 'lib/jss-api/client.rb', line 238

def self.serial_number
  self.hardware_data["serial_number"]
end

.udid ⇒ String

Returns the UUID/UDID for this computer.

Returns:

  • (String) —

    the UUID/UDID for this computer



231
232
233
 
# File 'lib/jss-api/client.rb', line 231

def self.udid
  self.hardware_data["platform_UUID"]
end