Class: JSS::Package
- Includes:
- Categorizable, Creatable, Updatable
- Defined in:
- lib/jss/api_object/package.rb,
lib/jss.rb
Overview
A Package in the JSS
Also the API provides no access to the package’s file list (index), so indexing must be done separately (usually via Casper Admin)
Constant Summary collapse
- RSRC_BASE =
The base for REST resources of this class
'packages'.freeze
- RSRC_LIST_KEY =
the hash key used for the JSON list output of all objects in the JSS
:packages
- RSRC_OBJECT_KEY =
The hash key used for the JSON object output. It’s also used in various error messages
:package
- VALID_DATA_KEYS =
these keys, as well as :id and :name, are present in valid API JSON data for this class
[:fill_existing_users, :fill_user_template, :reboot_required].freeze
- DIST_POINT_PKGS_FOLDER =
The pkg storage folder on the distribution point
'Packages'.freeze
- CPU_TYPES =
The possible values for cpu_type (required_processor) in a JSS package
%w(None x86 ppc).freeze
- PRIORITIES =
the possible priorities
(1..20)
- DEFAULT_PRIORITY =
the default priority, since one is needed for making new pkgs
10
- DEFAULT_PROCESSOR =
by default, no processor requirement
'None'.freeze
- DO_NOT_INSTALL =
When we shouldn’t install anything (e.g. switch w/package)
'Do Not Install'.freeze
- DB_TABLE =
The table in the database for this object
'packages'.freeze
Instance Attribute Summary collapse
-
#allow_uninstalled ⇒ Boolean
(also: #removable, #removable?)
Can this item be uninstalled? Some, e.g.
-
#boot_volume_required ⇒ Boolean
(also: #boot, #boot?)
Should this pkg be installed on the boot volume during imaging.
-
#filename ⇒ String
The filename of the .pkg, .mpkg, or .dmg on the Casper server.
-
#fill_existing_users ⇒ Boolean
(also: #feu, #feu?)
Does this item ‘Fill Existing Users’ when jamf installs it?.
-
#fill_user_template ⇒ Boolean
(also: #fut, #fut?)
Does this pkg also get install in the OS user homedir template.
-
#info ⇒ String
The info field for this pkg - stores d3’s basename & swupdate values.
-
#install_if_reported_available ⇒ Boolean
(also: #if_in_swupdate, #if_in_swupdate?)
Only install this pkg if it’s available in the commandline softwareupdate.
-
#need_to_update ⇒ Boolean
included
from Updatable
readonly
Do we have unsaved changes?.
-
#notes ⇒ String
The notes field for this pkg.
-
#os_requirements ⇒ Array<String>
(also: #oses)
The OS versions this can be installed onto.
-
#priority ⇒ Integer
Priority to use for deploying or uninstalling the package.
-
#reboot_required ⇒ Boolean
(also: #reboot, #reboot?)
Does this item require a reboot after installation? If so, it’ll be a puppy-install in d3.
-
#receipt ⇒ Pathname
readonly
The local receipt when this pkg is installed.
-
#required_processor ⇒ String
(also: #cpu_type)
Limit installation to these architectures: ‘x86’, ‘ppc’, ‘None’.
-
#send_notification ⇒ Boolean
(also: #notify)
Does this pkg cause a notification to be sent on self-heal?.
-
#switch_with_package ⇒ String
The name of a pkg to install (or “Do Not Install”) when this pkg can’t be installed.
Instance Method Summary collapse
-
#category=(new_cat) ⇒ void
included
from Categorizable
Change the category of this object.
-
#category_assigned? ⇒ Boolean
(also: #categorized?)
included
from Categorizable
Does this object have a category assigned?.
-
#category_id ⇒ Integer
included
from Categorizable
The id of the category for this object.
-
#category_name ⇒ String
(also: #category)
included
from Categorizable
The name of the category for this object.
-
#category_object ⇒ JSS::Category
included
from Categorizable
The JSS::Category instance for this object’s category.
-
#clone(new_name) ⇒ APIObject
included
from Creatable
make a clone of this API object, with a new name.
-
#create ⇒ Integer
included
from Creatable
Create a new object in the JSS.
-
#delete(delete_file: false, rw_pw: nil, unmount: true) ⇒ Object
Delete this package from the JSS, optionally deleting the master dist point file also.
-
#delete_master_file(rw_pw, unmount = true) ⇒ Boolean
Delete the filename from the master distribution point, if it exists.
-
#evaluate_new_category(new_cat) ⇒ Array<String, Integer>
included
from Categorizable
Given a category name or id, return the name and id.
-
#initialize(args = {}) ⇒ Package
constructor
A new instance of Package.
-
#install(args = {}) ⇒ Boolean
Install this package via the jamf binary ‘install’ command from the distribution point for this machine.
-
#installed? ⇒ Boolean
Is this packaged installed on the current machine (via casper)? We just look for the receipt, which is the @filename less any possible .zip extension.
-
#name=(newname) ⇒ void
included
from Updatable
Change the name of this item Remember to #update to push changes to the server.
-
#os_ok?(os = nil) ⇒ Boolean
Is a given OS OK for this package based on its @os_requirements?.
-
#processor_ok?(processor = nil) ⇒ Boolean
Is a given processor OK for this package based on its @required_processor?.
-
#type ⇒ Symbol
What type of package is this?.
-
#uninstall(args = {}) ⇒ Process::Status
Uninstall this pkg via the jamf command.
-
#unset_category ⇒ void
included
from Categorizable
Set the category to nothing.
-
#update ⇒ Boolean
included
from Updatable
Save changes to the JSS.
-
#update_master_filename(old_file_name, new_file_name, rw_pw, unmount = true) ⇒ nil
Change the name of a package file on the master distribution point.
-
#upload_master_file(local_file_path, rw_pw, unmount = true) ⇒ void
Upload a locally-readable file to the master distribution point.
Constructor Details
#initialize(args = {}) ⇒ Package
Returns a new instance of Package.
151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 |
# File 'lib/jss/api_object/package.rb', line 151 def initialize(args = {}) super ### now we have pkg_data with something in it, so fill out the instance vars @allow_uninstalled = @init_data[:allow_uninstalled] @boot_volume_required = @init_data[:boot_volume_required] @filename = @init_data[:filename] || @init_data[:name] @fill_existing_users = @init_data[:fill_existing_users] @fill_user_template = @init_data[:fill_user_template] @info = @init_data[:info] @install_if_reported_available = @init_data[:install_if_reported_available] @notes = @init_data[:notes] @os_requirements = @init_data[:os_requirements].split(/\s*,\s*/) if @init_data[:os_requirements] @os_requirements ||= [] @priority = @init_data[:priority] || DEFAULT_PRIORITY @reboot_required = @init_data[:reboot_required] @required_processor = @init_data[:required_processor] || DEFAULT_PROCESSOR @required_processor = nil if @required_processor.to_s.casecmp('none').zero? @send_notification = @init_data[:send_notification] @switch_with_package = @init_data[:switch_with_package] || DO_NOT_INSTALL # the receipt is the filename with any .zip extension removed. @receipt = @filename ? (JSS::Client::RECEIPTS_FOLDER + @filename.to_s.sub(/.zip$/, '')) : nil end |
Instance Attribute Details
#allow_uninstalled ⇒ Boolean Also known as: removable, removable?
Returns can this item be uninstalled? Some, e.g. OS Updates, can’t.
129 130 131 |
# File 'lib/jss/api_object/package.rb', line 129 def allow_uninstalled @allow_uninstalled end |
#boot_volume_required ⇒ Boolean Also known as: boot, boot?
Returns should this pkg be installed on the boot volume during imaging.
141 142 143 |
# File 'lib/jss/api_object/package.rb', line 141 def boot_volume_required @boot_volume_required end |
#filename ⇒ String
Returns the filename of the .pkg, .mpkg, or .dmg on the Casper server.
105 106 107 |
# File 'lib/jss/api_object/package.rb', line 105 def filename @filename end |
#fill_existing_users ⇒ Boolean Also known as: feu, feu?
Returns does this item ‘Fill Existing Users’ when jamf installs it?.
111 112 113 |
# File 'lib/jss/api_object/package.rb', line 111 def fill_existing_users @fill_existing_users end |
#fill_user_template ⇒ Boolean Also known as: fut, fut?
Returns does this pkg also get install in the OS user homedir template.
114 115 116 |
# File 'lib/jss/api_object/package.rb', line 114 def fill_user_template @fill_user_template end |
#info ⇒ String
Returns the info field for this pkg - stores d3’s basename & swupdate values.
132 133 134 |
# File 'lib/jss/api_object/package.rb', line 132 def info @info end |
#install_if_reported_available ⇒ Boolean Also known as: if_in_swupdate, if_in_swupdate?
Returns only install this pkg if it’s available in the commandline softwareupdate.
138 139 140 |
# File 'lib/jss/api_object/package.rb', line 138 def install_if_reported_available @install_if_reported_available end |
#need_to_update ⇒ Boolean (readonly) Originally defined in module Updatable
Returns do we have unsaved changes?.
#notes ⇒ String
Returns the notes field for this pkg.
135 136 137 |
# File 'lib/jss/api_object/package.rb', line 135 def notes @notes end |
#os_requirements ⇒ Array<String> Also known as: oses
Returns the OS versions this can be installed onto. For all minor versions, the format is 10.5.x.
120 121 122 |
# File 'lib/jss/api_object/package.rb', line 120 def os_requirements @os_requirements end |
#priority ⇒ Integer
Returns Priority to use for deploying or uninstalling the package.
144 145 146 |
# File 'lib/jss/api_object/package.rb', line 144 def priority @priority end |
#reboot_required ⇒ Boolean Also known as: reboot, reboot?
Returns does this item require a reboot after installation? If so, it’ll be a puppy-install in d3.
117 118 119 |
# File 'lib/jss/api_object/package.rb', line 117 def reboot_required @reboot_required end |
#receipt ⇒ Pathname (readonly)
Returns the local receipt when this pkg is installed.
108 109 110 |
# File 'lib/jss/api_object/package.rb', line 108 def receipt @receipt end |
#required_processor ⇒ String Also known as: cpu_type
Returns limit installation to these architectures: ‘x86’, ‘ppc’, ‘None’.
123 124 125 |
# File 'lib/jss/api_object/package.rb', line 123 def required_processor @required_processor end |
#send_notification ⇒ Boolean Also known as: notify
Returns does this pkg cause a notification to be sent on self-heal?.
147 148 149 |
# File 'lib/jss/api_object/package.rb', line 147 def send_notification @send_notification end |
#switch_with_package ⇒ String
Returns the name of a pkg to install (or “Do Not Install”) when this pkg can’t be installed.
126 127 128 |
# File 'lib/jss/api_object/package.rb', line 126 def switch_with_package @switch_with_package end |
Instance Method Details
#category=(new_cat) ⇒ void Originally defined in module Categorizable
This method returns an undefined value.
Change the category of this object. Any of the NON_CATEGORIES values will unset the category
#category_assigned? ⇒ Boolean Also known as: categorized? Originally defined in module Categorizable
Does this object have a category assigned?
#category_id ⇒ Integer Originally defined in module Categorizable
The id of the category for this object.
#category_name ⇒ String Also known as: category Originally defined in module Categorizable
The name of the category for this object. For backward compatibility, this is aliased to just ‘category’
#category_object ⇒ JSS::Category Originally defined in module Categorizable
The JSS::Category instance for this object’s category
#clone(new_name) ⇒ APIObject Originally defined in module Creatable
make a clone of this API object, with a new name. The class must be creatable
#create ⇒ Integer Originally defined in module Creatable
Create a new object in the JSS.
#delete(delete_file: false, rw_pw: nil, unmount: true) ⇒ Object
Delete this package from the JSS, optionally deleting the master dist point file also.
573 574 575 576 |
# File 'lib/jss/api_object/package.rb', line 573 def delete(delete_file: false, rw_pw: nil, unmount: true) super() delete_master_file(rw_pw, unmount) if delete_file end |
#delete_master_file(rw_pw, unmount = true) ⇒ Boolean
Delete the filename from the master distribution point, if it exists.
If you’ll be uploading several files you can specify unmount as false, and do it manually when all are finished.
550 551 552 553 554 555 556 557 558 559 560 561 |
# File 'lib/jss/api_object/package.rb', line 550 def delete_master_file(rw_pw, unmount = true) mdp = JSS::DistributionPoint.master_distribution_point file = mdp.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 did_it end |
#evaluate_new_category(new_cat) ⇒ Array<String, Integer> Originally defined in module Categorizable
Given a category name or id, return the name and id
#install(args = {}) ⇒ Boolean
deal with cert-based https authentication in dist points
This code must be run as root to install packages
Install this package via the jamf binary ‘install’ command from the distribution point for this machine. See DistributionPoint.my_distribution_point
The read-only or http passwd for the dist. point must be provided, except for non-authenticated http downloads)
618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 |
# File 'lib/jss/api_object/package.rb', line 618 def install(args = {}) raise JSS::UnsupportedError, 'You must have root privileges to install packages' unless JSS.superuser? args[:target] ||= '/' ro_pw = args[:ro_pw] # as of Casper 9.72, with http downloads, the jamf binary requires # the filename must be at the end of the -path url, but before 9.72 # it can't be. # e.g. # in <9.72: jamf install -package foo.pkg -path http://mycasper.myorg.edu/CasperShare/Packages # but # in >=9.72: jamf install -package foo.pkg -path http://mycasper.myorg.edu/CasperShare/Packages/foo.pkg # append_at_vers = JSS.parse_jss_version('9.72')[:version] our_vers = JSS.parse_jss_version(JSS.api_connection.server.raw_version)[:version] no_filename_in_url = (our_vers < append_at_vers) # use a provided alternative url for an http download if args[:alt_download_url] # we'll re-add the filename below if needed. src_path = args[:alt_download_url].chomp "/#{@filename}" # use our appropriate dist. point for download else mdp = JSS::DistributionPoint.my_distribution_point ### how do we access our dist. point? with http? if mdp.http_downloads_enabled && !(args[:no_http]) using_http = true src_path = mdp.http_url if mdp.username_password_required raise JSS::MissingDataError, 'No password provided for http download' unless ro_pw raise JSS::InvaldDatatError, 'Incorrect password for http access to distribution point.' unless mdp.check_pw(:http, ro_pw) # insert the name and pw into the uri # reserved_chars = Regexp.new("[^#{URI::REGEXP::PATTERN::UNRESERVED}]") # we'll escape all the chars that aren't unreserved src_path = src_path.sub(%r{(https?://)(\S)}, "#{Regexp.last_match(1)}#{CGI.escape mdp.http_username}:#{CGI.escape ro_pw}@#{Regexp.last_match(2)}") end # or with filesharing? else using_http = false src_path = mdp.mount(ro_pw) end # look at the pkgs folder src_path += "#{DIST_POINT_PKGS_FOLDER}/" end # if args[:alt_download_url] if using_http src_path += @filename.to_s unless no_filename_in_url end ### are we doing "fill existing users" or "fill user template"? do_feu = args[:feu] ? '-feu' : '' do_fut = args[:fut] ? '-fut' : '' ### the install args for jamf command_args = "-package '#{@filename}' -path '#{src_path}' -target '#{args[:target]}' #{do_feu} #{do_fut} -showProgress -verbose" ### run it via a client cmd install_out = JSS::Client.run_jamf :install, command_args, args[:verbose] install_out =~ %r{<exitCode>(\d+)</exitCode>} install_exit = Regexp.last_match(1) ? Regexp.last_match(1).to_i : nil install_exit ||= $CHILD_STATUS.exitstatus if args.include? :unmount mdp.unmount unless using_http end install_exit.zero? ? true : false end |
#installed? ⇒ Boolean
Is this packaged installed on the current machine (via casper)? We just look for the receipt, which is the @filename less any possible .zip extension.
437 438 439 |
# File 'lib/jss/api_object/package.rb', line 437 def installed? @receipt.file? end |
#name=(newname) ⇒ void Originally defined in module Updatable
This method returns an undefined value.
Change the name of this item Remember to #update to push changes to the server.
#os_ok?(os = nil) ⇒ Boolean
Is a given OS OK for this package based on its @os_requirements?
340 341 342 |
# File 'lib/jss/api_object/package.rb', line 340 def os_ok?(os = nil) JSS.os_ok? @os_requirements, os end |
#processor_ok?(processor = nil) ⇒ Boolean
Is a given processor OK for this package based on its @required_processor?
397 398 399 |
# File 'lib/jss/api_object/package.rb', line 397 def processor_ok?(processor = nil) JSS.processor_ok? @required_processor, processor end |
#type ⇒ Symbol
What type of package is this?
735 736 737 738 739 740 741 |
# File 'lib/jss/api_object/package.rb', line 735 def type case @filename when /\.m?pkg(\.zip)?$/ then :pkg when /\.dmg$/ then :dmg else :unknown end end |
#uninstall(args = {}) ⇒ Process::Status
This code must be run as root to uninstall packages
Uninstall this pkg via the jamf command.
710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 |
# File 'lib/jss/api_object/package.rb', line 710 def uninstall(args = {}) unless removable? raise JSS::UnsupportedError, \ 'This package cannot be uninstalled. Please use CasperAdmin to index it and allow uninstalls' end raise JSS::UnsupportedError, 'You must have root privileges to uninstall packages' unless JSS.superuser? args[:target] ||= '/' ### are we doing "fill existing users" or "fill user template"? do_feu = args[:feu] ? '-feu' : '' do_fut = args[:fut] ? '-fut' : '' ### use jamf binary to uninstall the pkg jamf_opts = "-target '#{args[:target]}' -id '#{@id}' #{do_feu} #{do_fut}" ### run it via a client JSS::Client.run_jamf 'uninstall', jamf_opts, args[:verbose] $CHILD_STATUS end |
#unset_category ⇒ void Originally defined in module Categorizable
This method returns an undefined value.
Set the category to nothing
#update ⇒ Boolean Originally defined in module Updatable
Save changes to the JSS
#update_master_filename(old_file_name, new_file_name, rw_pw, unmount = true) ⇒ nil
Change the name of a package file on the master distribution point.
521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 |
# File 'lib/jss/api_object/package.rb', line 521 def update_master_filename(old_file_name, new_file_name, rw_pw, unmount = true) raise JSS::NoSuchItemError, "#{old_file_name} does not exist in the jss." unless @in_jss mdp = JSS::DistributionPoint.master_distribution_point pkgs_dir = mdp.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? new_file = pkgs_dir + new_file_name ### use the extension of the original file. new_file = pkgs_dir + (new_file_name + old_file.extname) if new_file.extname.empty? old_file.rename new_file mdp.unmount if unmount nil end |
#upload_master_file(local_file_path, rw_pw, unmount = true) ⇒ void
This method returns an undefined value.
Upload a locally-readable file to the master distribution point. If the file is a directory (like a bundle .pk/.mpkg) it will be zipped before uploading and the @filename will be adjusted accordingly by adding a .zip extension
The name of the local file doesn’t matter, the file on the dist. point will use the @filename (possibly with .zip)
If you’ll be uploading several files you can specify unmount as false, and do it manually when all are finished with JSS::DistributionPoint.master_distribution_point.unmount
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 500 501 502 503 504 505 506 |
# File 'lib/jss/api_object/package.rb', line 460 def upload_master_file(local_file_path, rw_pw, unmount = true) raise JSS::NoSuchItemError, 'Please create this package in the JSS before uploading it.' unless @in_jss mdp = JSS::DistributionPoint.master_distribution_point destination = mdp.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? ### should we zip it? if local_path.directory? begin ### go to the same dir as the local file wd = Dir.pwd Dir.chdir local_path.parent ### the contents of the zip file have to have the same name as the zip file itself (minus the .zip) ### so temporarily rename the source local_path_to_upload = local_path.parent + @filename local_path.rename local_path_to_upload unless local_path_to_upload == local_path zipdir = Pathname.new "/tmp/rubyjsstmp-#{Time.new.strftime '%Y%m%d%H%M%S'}-#{$PROCESS_ID}" zipdir.mkpath zipdir.chmod 0o700 zipfile = zipdir + (local_path_to_upload.basename.to_s + '.zip') raise 'There was a problem zipping the pkg bundle' unless system "/usr/bin/zip -qr '#{zipfile}' '#{local_path_to_upload}'" ensure ### rename the source to the original name local_path_to_upload.rename local_path if local_path_to_upload.exist? && local_path_to_upload != local_path ### go back where we started Dir.chdir wd end # begin ### update our info local_path = zipfile destination = destination.to_s + '.zip' @filename = zipfile.basename.to_s @need_to_update = true update end # if directory FileUtils.copy_entry local_path, destination mdp.unmount if unmount end |