zoocoup · October 13, 2015 06:57
diff --git a/Preventing Installation Errors When Deploying Software With Casper 8.x b/Preventing Installation Errors When Deploying Software With Casper 8.x
 # These are issues I ran into based on how I use Casper. Your experience might vary.
 # Last Edit - 20131008 jkb | @zoocoup 

 Casper's error checking and reporting isn't sophisticated or exact; sometimes an error isn't really an error. 
 It is possible for a policy to fail a first or second time and then be successful on a subsequent attempt. Be sure 
 to check status log and/or client detailed inventory before flushing policy and running again or 
 troubleshooting the package/process.

 _Scripts Are Not Written Properly_
 If you have a syntax error in a script, the script will fail and Casper will throw a policy error. Depending on 
 the actions the script is performing:
 1. the script's actions might completely fail and an error will result: 
 a. If you are using a script to collect data and it fails to properly collect that data, Casper will throw 
 an error that looks severe but is not.
 b. If you are using a script to install software or files and it fails, Casper will throw an error based on the 
 script's error return. Time to rewrite your script.
 2. the script might only fail in part and even though Casper reports an error, depending on the script's 
 actions, the install might still be successful

 Common syntax errors:
 	- Calling a cached package that hasn't actually been cached
 	- Calling the wrong DMG or PKG name (path wrong, wrong file is called, incomplete name used, etc)

 _Application to be Updated is Running_
 This is common with Adobe and Microsoft application updaters. Casper might report in the error log that 
 the installer failed because "the application is running" or that "the manufacture should be contacted". You will 
 need to script the shutdown of the application to be updated and run the script before applying the update or, applicable in some
 cases, you can negate the need to quit the application by calling a Choice Changes XML file that has a No Quit option.

 _Smart Groups (or Receipts) Might Fail You_
 1. If using policy to run softwareupdate to install Apple updates in the background on a client, it's possible 
 that in between the time when an install Smart Group targeting clients that need "Update X" was created and before 
 the install policy to install "Update X" is ran by clients that the user has manually installed "Update X", thus negating 
 the need for the update to be installed. If this happens, softwareupdate will list no updates available to install 
 and Casper will error.

 Related: softwareupdate might also fail because corrupt package receipts on the client force an error. If the 
 softwareupdate -ia command, which will install all available updates, is called by policy, it is possible for 
 corrupt package receipts in /Library/Receipts (e.g. Microsoft Office 2008, older versions of Cisco VPN) on a 
 client to cause an error in the listing of updates and bork the install process, resulting in an policy error.

 Additional Related: if using softwareupdate -i xxxx to install an update on an entire fleet, it is possible for errors to occur 
 if that update is not required for particular machines, e.g. softwareupdate -i Xerox-Printer-Drivers2.1 might fail on 
 machines for which the Xerox drivers have not been previously installed and thus are not listed as an available update.

 2. If using a Smart Group to scope on a particular value, such as application version, it is possible that 
 before policy is picked up by the client that the smart value will change and the client machine will no 
 longer meet the smart group criteria. If this happens, it's possible that the update is no longer needed 
 and Casper will error.

 _Spaces in DMG package names_
 Avoid using spaces in package names as clients might fail to properly escape the spaces and report that the 
 package can not be found.

 _System Requirements Not Met_
 1. If using a native installer rather than a repacked DMG package install, it is possible for a preflight script 
 that checks for a required previous version of the software to cancel installation.
 2. Policy scope could include machines that do not meet requirements of software (e.g. wrong OS or dependent application not present).
 	
 _PKG and MPKG File Issues_
 If using native .pkg or .mpkg files rather than a repackaged DMG package, it is possible for installation 
 to fail because:
 1. .pkg file is actually an alias package that points at a different package that was not uploaded to JSS
 2. .mpkg file "breaks" during download to the client because during transfer the entire file is 
 not transmitted
 3. Some .mpkg files are not properly recognized by the JSS via Casper Admin. That is, files appear to be 
 successfully uploaded, but if you check http://jss/CasperShare, they are not available packages
 Solutions:
 	- If possible, convert to a Casper DMG package with Composer
 	- Wrap .mpkg in a DMG wrapper, then use installfromDMG script to call cached installer 
        - Use flat packages  

 _Hung jamf Process_
 Though it shouldn't happen, it is possible that a previously run jamf process has hung/is still left running 
 and prevents the proper running of new jamf process. Thus the machine does not properly process new install policies. 
 To correct, quit the stale process or, if needed, restart the client machine.  

 _Applications Fails to Launch_
 The following are errors that might occur after a package has been successfully installed, from an 
 installation stand point, but fail because the application does not properly operate on the client machine.	
 1. When installing from DMG, Casper does not always overwrite existing application bundles. As such, an 
 application might fail to launch after install because the installation is corrupted; the install has bits 
 of the old version and bits of the new version in place. The solution is to use a script to remove the previous 
 version before installing the new version.
 2. The package contains user home folder files that were not installed. If user-level files are included in 
 the package, enable the option to install those files in user home folders in Casper Admin or in the policy creation.

 _Addendum_
 A. If the JSS has been configured to distribute updates via HTTP download, it's possible for errors to be introduced into 
 the update process by communication issues with/from the web server to the client. The jamf binary on the client machine 
 use CURL to get packages from the JSS. Due to errors communicating with the web server, installation errors might occur 
 because packages are not properly retrieved from the JSS.

 Policy error logs will present an error such as this: 
 "Error: Package not successfully downloaded:[code number]” The code number is a CURL error code. See this listing 
 for a full list of codes and their meanings: http://curl.haxx.se/libcurl/c/libcurl-errors.html

 B. If there is a before action script set to run, e.g. display a message to the user before running an update, and the machine 
 is at the Login Window when the policy is run the install will generate an error message. Parse the error log carefully, 
 more than likely only the script failed, because it can't call jamfHelper at the Login Window, but the package was still 
 successfully installed.
	# These are issues I ran into based on how I use Casper. Your experience might vary.
	# Last Edit - 20131008 jkb \| @zoocoup

	Casper's error checking and reporting isn't sophisticated or exact; sometimes an error isn't really an error.
	It is possible for a policy to fail a first or second time and then be successful on a subsequent attempt. Be sure
	to check status log and/or client detailed inventory before flushing policy and running again or
	troubleshooting the package/process.

	_Scripts Are Not Written Properly_
	If you have a syntax error in a script, the script will fail and Casper will throw a policy error. Depending on
	the actions the script is performing:
	1. the script's actions might completely fail and an error will result:
	a. If you are using a script to collect data and it fails to properly collect that data, Casper will throw
	an error that looks severe but is not.
	b. If you are using a script to install software or files and it fails, Casper will throw an error based on the
	script's error return. Time to rewrite your script.
	2. the script might only fail in part and even though Casper reports an error, depending on the script's
	actions, the install might still be successful

	Common syntax errors:
	- Calling a cached package that hasn't actually been cached
	- Calling the wrong DMG or PKG name (path wrong, wrong file is called, incomplete name used, etc)

	_Application to be Updated is Running_
	This is common with Adobe and Microsoft application updaters. Casper might report in the error log that
	the installer failed because "the application is running" or that "the manufacture should be contacted". You will
	need to script the shutdown of the application to be updated and run the script before applying the update or, applicable in some
	cases, you can negate the need to quit the application by calling a Choice Changes XML file that has a No Quit option.

	_Smart Groups (or Receipts) Might Fail You_
	1. If using policy to run softwareupdate to install Apple updates in the background on a client, it's possible
	that in between the time when an install Smart Group targeting clients that need "Update X" was created and before
	the install policy to install "Update X" is ran by clients that the user has manually installed "Update X", thus negating
	the need for the update to be installed. If this happens, softwareupdate will list no updates available to install
	and Casper will error.

	Related: softwareupdate might also fail because corrupt package receipts on the client force an error. If the
	softwareupdate -ia command, which will install all available updates, is called by policy, it is possible for
	corrupt package receipts in /Library/Receipts (e.g. Microsoft Office 2008, older versions of Cisco VPN) on a
	client to cause an error in the listing of updates and bork the install process, resulting in an policy error.

	Additional Related: if using softwareupdate -i xxxx to install an update on an entire fleet, it is possible for errors to occur
	if that update is not required for particular machines, e.g. softwareupdate -i Xerox-Printer-Drivers2.1 might fail on
	machines for which the Xerox drivers have not been previously installed and thus are not listed as an available update.

	2. If using a Smart Group to scope on a particular value, such as application version, it is possible that
	before policy is picked up by the client that the smart value will change and the client machine will no
	longer meet the smart group criteria. If this happens, it's possible that the update is no longer needed
	and Casper will error.

	_Spaces in DMG package names_
	Avoid using spaces in package names as clients might fail to properly escape the spaces and report that the
	package can not be found.

	_System Requirements Not Met_
	1. If using a native installer rather than a repacked DMG package install, it is possible for a preflight script
	that checks for a required previous version of the software to cancel installation.
	2. Policy scope could include machines that do not meet requirements of software (e.g. wrong OS or dependent application not present).

	_PKG and MPKG File Issues_
	If using native .pkg or .mpkg files rather than a repackaged DMG package, it is possible for installation
	to fail because:
	1. .pkg file is actually an alias package that points at a different package that was not uploaded to JSS
	2. .mpkg file "breaks" during download to the client because during transfer the entire file is
	not transmitted
	3. Some .mpkg files are not properly recognized by the JSS via Casper Admin. That is, files appear to be
	successfully uploaded, but if you check http://jss/CasperShare, they are not available packages
	Solutions:
	- If possible, convert to a Casper DMG package with Composer
	- Wrap .mpkg in a DMG wrapper, then use installfromDMG script to call cached installer
	- Use flat packages

	_Hung jamf Process_
	Though it shouldn't happen, it is possible that a previously run jamf process has hung/is still left running
	and prevents the proper running of new jamf process. Thus the machine does not properly process new install policies.
	To correct, quit the stale process or, if needed, restart the client machine.

	_Applications Fails to Launch_
	The following are errors that might occur after a package has been successfully installed, from an
	installation stand point, but fail because the application does not properly operate on the client machine.
	1. When installing from DMG, Casper does not always overwrite existing application bundles. As such, an
	application might fail to launch after install because the installation is corrupted; the install has bits
	of the old version and bits of the new version in place. The solution is to use a script to remove the previous
	version before installing the new version.
	2. The package contains user home folder files that were not installed. If user-level files are included in
	the package, enable the option to install those files in user home folders in Casper Admin or in the policy creation.

	_Addendum_
	A. If the JSS has been configured to distribute updates via HTTP download, it's possible for errors to be introduced into
	the update process by communication issues with/from the web server to the client. The jamf binary on the client machine
	use CURL to get packages from the JSS. Due to errors communicating with the web server, installation errors might occur
	because packages are not properly retrieved from the JSS.

	Policy error logs will present an error such as this:
	"Error: Package not successfully downloaded:[code number]” The code number is a CURL error code. See this listing
	for a full list of codes and their meanings: http://curl.haxx.se/libcurl/c/libcurl-errors.html

	B. If there is a before action script set to run, e.g. display a message to the user before running an update, and the machine
	is at the Login Window when the policy is run the install will generate an error message. Parse the error log carefully,
	more than likely only the script failed, because it can't call jamfHelper at the Login Window, but the package was still
	successfully installed.