zoocoup/Preventing Installation Errors When Deploying Software With Casper 8.x

## 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.