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
- OBJECT_HISTORY_OBJECT_TYPE =
the object type for this object in the object history table. See APIObject#add_object_history_entry
90
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, api: nil) ⇒ APIObject
included
from Creatable
make a clone of this API object, with a new name.
-
#create(api: nil) ⇒ 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 TODO: use APIObject.exist? and/or APIObject.valid_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.
156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 |
# File 'lib/jss/api_object/package.rb', line 156 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.
134 135 136 |
# File 'lib/jss/api_object/package.rb', line 134 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.
146 147 148 |
# File 'lib/jss/api_object/package.rb', line 146 def boot_volume_required @boot_volume_required end |
#filename ⇒ String
Returns the filename of the .pkg, .mpkg, or .dmg on the Casper server.
110 111 112 |
# File 'lib/jss/api_object/package.rb', line 110 def filename @filename end |
#fill_existing_users ⇒ Boolean Also known as: feu, feu?
Returns does this item ‘Fill Existing Users’ when jamf installs it?.
116 117 118 |
# File 'lib/jss/api_object/package.rb', line 116 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.
119 120 121 |
# File 'lib/jss/api_object/package.rb', line 119 def fill_user_template @fill_user_template end |
#info ⇒ String
Returns the info field for this pkg - stores d3’s basename & swupdate values.
137 138 139 |
# File 'lib/jss/api_object/package.rb', line 137 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.
143 144 145 |
# File 'lib/jss/api_object/package.rb', line 143 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.
140 141 142 |
# File 'lib/jss/api_object/package.rb', line 140 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.
125 126 127 |
# File 'lib/jss/api_object/package.rb', line 125 def os_requirements @os_requirements end |
#priority ⇒ Integer
Returns Priority to use for deploying or uninstalling the package.
149 150 151 |
# File 'lib/jss/api_object/package.rb', line 149 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.
122 123 124 |
# File 'lib/jss/api_object/package.rb', line 122 def reboot_required @reboot_required end |
#receipt ⇒ Pathname (readonly)
Returns the local receipt when this pkg is installed.
113 114 115 |
# File 'lib/jss/api_object/package.rb', line 113 def receipt @receipt end |
#required_processor ⇒ String Also known as: cpu_type
Returns limit installation to these architectures: ‘x86’, ‘ppc’, ‘None’.
128 129 130 |
# File 'lib/jss/api_object/package.rb', line 128 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?.
152 153 154 |
# File 'lib/jss/api_object/package.rb', line 152 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.
131 132 133 |
# File 'lib/jss/api_object/package.rb', line 131 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, api: nil) ⇒ APIObject Originally defined in module Creatable
make a clone of this API object, with a new name. The class must be creatable
#create(api: nil) ⇒ 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.
578 579 580 581 |
# File 'lib/jss/api_object/package.rb', line 578 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.
555 556 557 558 559 560 561 562 563 564 565 566 |
# File 'lib/jss/api_object/package.rb', line 555 def delete_master_file(rw_pw, unmount = true) mdp = JSS::DistributionPoint.master_distribution_point api: @api 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 TODO: use APIObject.exist? and/or APIObject.valid_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)
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 693 694 695 696 697 |
# File 'lib/jss/api_object/package.rb', line 623 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(@api.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 api: @api ### 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.
442 443 444 |
# File 'lib/jss/api_object/package.rb', line 442 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?
345 346 347 |
# File 'lib/jss/api_object/package.rb', line 345 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?
402 403 404 |
# File 'lib/jss/api_object/package.rb', line 402 def processor_ok?(processor = nil) JSS.processor_ok? @required_processor, processor end |
#type ⇒ Symbol
What type of package is this?
740 741 742 743 744 745 746 |
# File 'lib/jss/api_object/package.rb', line 740 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.
715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 |
# File 'lib/jss/api_object/package.rb', line 715 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.
526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 |
# File 'lib/jss/api_object/package.rb', line 526 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 api: @api 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
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 507 508 509 510 511 |
# File 'lib/jss/api_object/package.rb', line 465 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 api: @api 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 |