zoocoup/Casper Packaging & Deployment

## Casper Packaging & Deployment
Casper Packaging & Deployment

# This document was made for my coworkers as I was leaving a previous job. The content should
# be applicable in most environments.
# Last Edit 20131008 - jkb | @zoocoup


This document is an overview of packaging applications, plug-ins and files or deployment with Casper.

_Testing the Application_
Before spending the time building a package to deploy an application or plug-in, test it on several machines to makes sure it does what it’s suppose to do (Does printing work? Saving to network shares work? Does it playback media files properly?) Build a testing criteria based on how you expect the application to work and then test against that criteria. Testing also provides the opportunity to learn where in the file system an application references files from during use. You’ll need to make sure these files are included in any packages you make.

I test applications on my workstation, in OS X virtual machines* running on my workstation, on spare|loaner machines, on shared machines, and, when needed to test a specific application function, on select end user machines.

* VMs don’t always perform the same as physical machines. A fault in a VM, such as a video glitch, might not be an issue with a physical machine.

_Making the Package_
Determining what should be included in a package file involves a combination of research, observation, testing, use and experience. Using an application gives you some information. Taking apart the original package will yield more details. Using utilities like fseventer or Composer’s Monitor File System Changes snapshotting feature can expose parts of an application you wouldn’t at first expect. Having a good grasp of the OS X file system and knowing where you might expect application files to be** is an asset. When in doubt if a particular directory or file needs to be included in a package — some installers create directories that don’t need to exist on client machines for operation, and some create directories, even if initially empty, which must be present for successful operation — your best course of action is always to build a package, test it and then rebuild it if necessary, expanding or contracting the number of included items.

**For most installers, the common install locations are: /Applications, /Library/Application Support, /Library/Intern Plug-ins, /Library/Preferences and the similar location in user’s home folders.

*Building the Package*
You first need to decide if there is a reason for making a package. If an original, developer-made installer will work successfully when deployed from your JSS, why remake it? There might be a need to customize the installed application’s experience for end users, but that doesn’t mean you have to completely repackage the installer. Instead you could build a second package that includes just your customizations.
Application testing will help you determine if you need to repackage, but some common reasons to create a new package are:
	a. The original package is not made well and is likely to fail when mass deployed
	b. The original package installs several components, yet you need to install only select components and a ChoiceChanges.XML file will not work
	c. The original package requires a user to be logged in during installation or requires unneeded user interaction
	d. You want to include custom content in a single installer rather than having sets of packages to build and track.

This document assumes you will use JAMF Composer to create packages. Other available tools include
packagemaker and pkgbuild, both CLI tools built into OS X 10.8, Apple PackageMaker, Iceberg and Packages (both from WhiteBox) and Absolute Manage InstallEase. Composer has the benefit of having built-in snapshot tools, drag and drop file placement and ability to export both DMG and PKG file formats. Certain Adobe applications will require the use of Adobe’s packaging tools (Customization Wizard for Acrobat or Creative Cloud Packager).

It is difficult to give a step-by-step set of instructions for creating a package installer. Every application installs different files, and each installation type and client set will add additional variables. In lieu of explicit instructions, a repackaged Adobe Flash Player installer can serve as a common example:

			+ /Applications
				+ /Utilities
					+ Adobe Flash Player Install Manager.app
			+ /Library
				+ /Application Support
					+ /Adobe
						+ /Flash Player Install Manager
							FPSAUConfig.xml
							fpsaud
					+ /Macromedia
						mms.cfg
				+ /Internet Plug-ins
					+ Flash Player.plugin
					+ flashplayer.xpt
				+ /LaunchDaemons
					+ com.adobe.fpsaud.plist
				+ /PreferencePanes
					+ Flash Player.prefPane

From the top of the package list, this is why the following files were included:
- /Applications/Utilities/Adobe Flash Player Install Manager.app: through testing it was discovered that without this application, the Flash System Pane would fail to work
- /Library/Application Support/Adobe/Flash Player Install Manager/*: binary behind the above application and configuration file
- /Library/Application Support/Macromedia/mms.cfg: configuration file
- /Library/Internet Plug-ins/Flash Player.plugin and flashplayer.xpt: the Flash Player “magic”
- /Library/LaunchDaemons/com.adobe.fpsaud.plist: needed by Flash Player manager
- /Library/PreferencePanes/Flash Player.prefPane: the System Prefernces Flash Player system pane


Arriving at the list of files to include in the Adobe Flash Player installer involved using Composer’s snapshot feature to capture a file listing, and then cleaning out files that were not needed based on testing and awareness of the file system**. When in doubt, build a package, test the package and then trim contents from the package if needed.

** If you are installing Adobe Flash Player, there’s not a need to install files from /Library/Application Support/Google Earth, for example. Composer’s snapshot feature captured those references during an installation because there was background activity going on during installation.

If you need to deploy files to user home folders, such as per user configuration file that must be installed in ~/Library/Preferences, you will have to use the FEU (Fill Existing User) and FUT (Fill User Template) options in policy to deploy these files. Casper will automatically place the files in the proper place in /Users and /System/Library/User Template. Composer builds a package with the user folder named after the user creating the package. This user folder name will be ignored during deployment; it’s just a placeholder.

Recommended practices when building any package:
Open the application or call on the plug-in multiple times before you start building the package. Some applications install additional items after initial launch. Keep quitting and opening the application until it stops asking for authentication or asking to install items.
Use ls -al@  to determine if files and applications have the quarantine flag (com.apple.quarantine— what triggers the “X is an application downloaded from the Internet…” dialog in the Finder) and xattr -r -d com.apple.quarantine [/path/to/files] to remove the flag from files before assembly the package files.
Correct permissions on all applications and files either before assembling package files or by using Composer to correct permissions on the package’s files. Failure to apply proper permissions could result in issues on client machines. Correct permissions will vary depending on where in the file system the files are being installed.
Do not use spaces in package names. Spaces in names can cause issues when clients attempt to download the files from the JSS because the spaces are not always properly ignored. I use the following naming convention because it helps with tracking package versions: [product name]_[version]_(Upg or Full)_[Date created], e.g.: MicrosoftOffice2011_14.3.7_FullInstaller_20131010 or GoogleEarth_7.1.1888_20131003
If building a package that will update an existing application, include the entire application bundle in the update package. For example, if building an update for Adobe Acrobat Pro that will update clients from version 11.0.03 to 11.0.04, your update package will include any new or changed files from /Library/Application Support and could just include the updated files in /Applications/Adobe Acrobat Pro.app, but if you instead include the updated support files and the entire Adobe Acrobat Pro.app, rather than just the differing application files, your package will be more stable and allow you to update a broader range of clients (you can make a “combo” updater that updates 11.0.00 - 11.0.03 clients).

Composer can create packages in two different file formats: DMG and PKG. What you need to deploy and how you want to deploy it help determine which format to use. If you want to install files in users’ homes or in the User Template, you must use a DMG file. If you want to run pre-fight or post-flight scripts that are part of the package, rather than scripts that run as part of the deployment policy, then you must build a PKG file.
DMG files are generally used for larger, more complex installations and PKG files used for “simple” installs. You can build both formats and test if there is a question of what will work best for the stated need.

There is what can be considered a third type of package: a staging package. There are situations where you do not want to or can not repackage an original developer-made installer, but that installer can not be cleanly deployed from the JSS. The solution is to create a package that places the developer installer on the client machine, in a location such as /tmp or /Users/Shared, and then uses a policy script to install that package and clean up any files once the installation is complete.

*Testing the Package*
After you have built your package file, you’ll need to test. You can use the jamf binary to simulate the behavior of installing from the JSS without having to upload packages to the JSS. The number of tests you run will depend on the complexity of the install, and the confidence in the package. I recommend testing the package on at least two to three machines. Better to find a mistake now then before an install is attempted on the entire fleet of client machines.

_Deploying the Package_
Once the packages are made and have been successfully tested, they will need to be uploaded to the JSS using Casper Admin.app. The Casper Administrator guide provides complete instructions for using Casper Admin and creating policies.

*Checklist*
Based on experience, I recommend creating a package upload and policy creation checklist. More than likely you will be uploading several packages and/or policies at once, and a checklist will help keep you organized without skipping over a needed step.

An ideal checklist will include the following:
The package Display name
The JSS category that best represents the package’s intent
The scope of client machines the package will be applied to
If the the FEU or FUT install options should be used
If any policy scripts need to be run before or after the package is installed
The date the package policy will become active
Should the package be restricted to certain OSes?

If you apply this checklist to each package, using it as a guide for applying metadata in Casper Admin.app and for checkpoints when creating the deployment policy in the JSS, it should help prevent common policy creation errors.

*Scripts*
Some packages need to be augmented with scripts (this is usually determined during testing). When creating a policy, you can have a script run before a particular package is installed (this could be used to remove a previously existing/older version of an application before installing a new version or to backup user data files before an application is installed) or a script can run after a package is installed (to launch the newly installed application, for example). The same advice for packages applies to scripts: test them on a number of machines before using them in production.

*Previous Policies*
Based on experience, I keep the previous version of a policy (N-1) as a safety. Better to have a fallback in the event a new package and policy experiences issues in production than to have to recreate past work.

_Tools_
*GUI Tools*
JAMF Composer: Package making utility. Can generate both DMG and PKG format files.
JAMF Casper Admin: Used to upload files to the JSS and apply metadata to those files.
BareBones TextWrangler: Text editor that can read and write plist files.
fernLightning fseventer: GUI tool for observing file system events as they happen. Useful for seeing which files and directories are used by an application.

*Command-Line Tools*
All are built into the OS with the exception of jamf, which is installed only on enrolled machines. See the man pages for full details.
pkgutil: Utility to get information about installed packages and examine individual packages.
The following command will use pkgutil to expose the contents of a flat package file so that you can examine what a package is installing in greater depth.

	pkgutil --expand [pkg file] /path/to/folder/to/expand/contents/to

xattr: Utility to manipulate extended attributes on files and folders. xattr might be needed to remove quarantine warnings from installed files using the following:

	xattr -r -d com.apple.quarantine /path/to/files

You can view the extended attributes on an application using the following command:
	ls -al@

Installer: CLI version of Installer.app. Has a larger number of options than GUI version. Used in scripts to install applications from a staged package. Also used when a ChoiceChangesXML needs to be used, e.g.

	installer -pkg /Users/Shared/OfficeUpg14.3.7/Office201114.3.7Update.pkg
	-applyChoiceChangesXML /Users/Shared/OfficeUpg14.3.7/NoQuit.xml -target /

jamf:  Binary that does all of the client-side work for Casper. The jamf binary is used as a way to test packages before uploading them to the JSS using the following:
	jamf install -package [package file] -path [/to/package/file]
	-target / -feu -fut

Install is the verb in the command string telling the jamf binary what action to do. Packages can be either .pkg or .dmg files. The -packages flag is looking for the name of the package. Path is the path to the package file location. FEU = Fill Existing Users (homes with files). FUT = Fill User Template (all newly created user homes will have files). The target is almost always the root (/) volume. Example:

jamf install -package GoogleEarth_7.1.1888_20130924 -path /Volumes/testdisk -target / -fut -feu
	Casper Packaging & Deployment

	# This document was made for my coworkers as I was leaving a previous job. The content should
	# be applicable in most environments.
	# Last Edit 20131008 - jkb \| @zoocoup


	This document is an overview of packaging applications, plug-ins and files or deployment with Casper.

	_Testing the Application_
	Before spending the time building a package to deploy an application or plug-in, test it on several machines to makes sure it does what it’s suppose to do (Does printing work? Saving to network shares work? Does it playback media files properly?) Build a testing criteria based on how you expect the application to work and then test against that criteria. Testing also provides the opportunity to learn where in the file system an application references files from during use. You’ll need to make sure these files are included in any packages you make.

	I test applications on my workstation, in OS X virtual machines* running on my workstation, on spare\|loaner machines, on shared machines, and, when needed to test a specific application function, on select end user machines.

	* VMs don’t always perform the same as physical machines. A fault in a VM, such as a video glitch, might not be an issue with a physical machine.

	_Making the Package_
	Determining what should be included in a package file involves a combination of research, observation, testing, use and experience. Using an application gives you some information. Taking apart the original package will yield more details. Using utilities like fseventer or Composer’s Monitor File System Changes snapshotting feature can expose parts of an application you wouldn’t at first expect. Having a good grasp of the OS X file system and knowing where you might expect application files to be** is an asset. When in doubt if a particular directory or file needs to be included in a package — some installers create directories that don’t need to exist on client machines for operation, and some create directories, even if initially empty, which must be present for successful operation — your best course of action is always to build a package, test it and then rebuild it if necessary, expanding or contracting the number of included items.

	**For most installers, the common install locations are: /Applications, /Library/Application Support, /Library/Intern Plug-ins, /Library/Preferences and the similar location in user’s home folders.

	Building the Package
	You first need to decide if there is a reason for making a package. If an original, developer-made installer will work successfully when deployed from your JSS, why remake it? There might be a need to customize the installed application’s experience for end users, but that doesn’t mean you have to completely repackage the installer. Instead you could build a second package that includes just your customizations.
	Application testing will help you determine if you need to repackage, but some common reasons to create a new package are:
	a. The original package is not made well and is likely to fail when mass deployed
	b. The original package installs several components, yet you need to install only select components and a ChoiceChanges.XML file will not work
	c. The original package requires a user to be logged in during installation or requires unneeded user interaction
	d. You want to include custom content in a single installer rather than having sets of packages to build and track.

	This document assumes you will use JAMF Composer to create packages. Other available tools include
	packagemaker and pkgbuild, both CLI tools built into OS X 10.8, Apple PackageMaker, Iceberg and Packages (both from WhiteBox) and Absolute Manage InstallEase. Composer has the benefit of having built-in snapshot tools, drag and drop file placement and ability to export both DMG and PKG file formats. Certain Adobe applications will require the use of Adobe’s packaging tools (Customization Wizard for Acrobat or Creative Cloud Packager).

	It is difficult to give a step-by-step set of instructions for creating a package installer. Every application installs different files, and each installation type and client set will add additional variables. In lieu of explicit instructions, a repackaged Adobe Flash Player installer can serve as a common example:

	+ /Applications
	+ /Utilities
	+ Adobe Flash Player Install Manager.app
	+ /Library
	+ /Application Support
	+ /Adobe
	+ /Flash Player Install Manager
	FPSAUConfig.xml
	fpsaud
	+ /Macromedia
	mms.cfg
	+ /Internet Plug-ins
	+ Flash Player.plugin
	+ flashplayer.xpt
	+ /LaunchDaemons
	+ com.adobe.fpsaud.plist
	+ /PreferencePanes
	+ Flash Player.prefPane

	From the top of the package list, this is why the following files were included:
	- /Applications/Utilities/Adobe Flash Player Install Manager.app: through testing it was discovered that without this application, the Flash System Pane would fail to work
	- /Library/Application Support/Adobe/Flash Player Install Manager/*: binary behind the above application and configuration file
	- /Library/Application Support/Macromedia/mms.cfg: configuration file
	- /Library/Internet Plug-ins/Flash Player.plugin and flashplayer.xpt: the Flash Player “magic”
	- /Library/LaunchDaemons/com.adobe.fpsaud.plist: needed by Flash Player manager
	- /Library/PreferencePanes/Flash Player.prefPane: the System Prefernces Flash Player system pane


	Arriving at the list of files to include in the Adobe Flash Player installer involved using Composer’s snapshot feature to capture a file listing, and then cleaning out files that were not needed based on testing and awareness of the file system**. When in doubt, build a package, test the package and then trim contents from the package if needed.

	** If you are installing Adobe Flash Player, there’s not a need to install files from /Library/Application Support/Google Earth, for example. Composer’s snapshot feature captured those references during an installation because there was background activity going on during installation.

	If you need to deploy files to user home folders, such as per user configuration file that must be installed in ~/Library/Preferences, you will have to use the FEU (Fill Existing User) and FUT (Fill User Template) options in policy to deploy these files. Casper will automatically place the files in the proper place in /Users and /System/Library/User Template. Composer builds a package with the user folder named after the user creating the package. This user folder name will be ignored during deployment; it’s just a placeholder.

	Recommended practices when building any package:
	Open the application or call on the plug-in multiple times before you start building the package. Some applications install additional items after initial launch. Keep quitting and opening the application until it stops asking for authentication or asking to install items.
	Use ls -al@ to determine if files and applications have the quarantine flag (com.apple.quarantine— what triggers the “X is an application downloaded from the Internet…” dialog in the Finder) and xattr -r -d com.apple.quarantine [/path/to/files] to remove the flag from files before assembly the package files.
	Correct permissions on all applications and files either before assembling package files or by using Composer to correct permissions on the package’s files. Failure to apply proper permissions could result in issues on client machines. Correct permissions will vary depending on where in the file system the files are being installed.
	Do not use spaces in package names. Spaces in names can cause issues when clients attempt to download the files from the JSS because the spaces are not always properly ignored. I use the following naming convention because it helps with tracking package versions: [product name]_[version]_(Upg or Full)_[Date created], e.g.: MicrosoftOffice2011_14.3.7_FullInstaller_20131010 or GoogleEarth_7.1.1888_20131003
	If building a package that will update an existing application, include the entire application bundle in the update package. For example, if building an update for Adobe Acrobat Pro that will update clients from version 11.0.03 to 11.0.04, your update package will include any new or changed files from /Library/Application Support and could just include the updated files in /Applications/Adobe Acrobat Pro.app, but if you instead include the updated support files and the entire Adobe Acrobat Pro.app, rather than just the differing application files, your package will be more stable and allow you to update a broader range of clients (you can make a “combo” updater that updates 11.0.00 - 11.0.03 clients).

	Composer can create packages in two different file formats: DMG and PKG. What you need to deploy and how you want to deploy it help determine which format to use. If you want to install files in users’ homes or in the User Template, you must use a DMG file. If you want to run pre-fight or post-flight scripts that are part of the package, rather than scripts that run as part of the deployment policy, then you must build a PKG file.
	DMG files are generally used for larger, more complex installations and PKG files used for “simple” installs. You can build both formats and test if there is a question of what will work best for the stated need.

	There is what can be considered a third type of package: a staging package. There are situations where you do not want to or can not repackage an original developer-made installer, but that installer can not be cleanly deployed from the JSS. The solution is to create a package that places the developer installer on the client machine, in a location such as /tmp or /Users/Shared, and then uses a policy script to install that package and clean up any files once the installation is complete.

	Testing the Package
	After you have built your package file, you’ll need to test. You can use the jamf binary to simulate the behavior of installing from the JSS without having to upload packages to the JSS. The number of tests you run will depend on the complexity of the install, and the confidence in the package. I recommend testing the package on at least two to three machines. Better to find a mistake now then before an install is attempted on the entire fleet of client machines.

	_Deploying the Package_
	Once the packages are made and have been successfully tested, they will need to be uploaded to the JSS using Casper Admin.app. The Casper Administrator guide provides complete instructions for using Casper Admin and creating policies.

	Checklist
	Based on experience, I recommend creating a package upload and policy creation checklist. More than likely you will be uploading several packages and/or policies at once, and a checklist will help keep you organized without skipping over a needed step.

	An ideal checklist will include the following:
	The package Display name
	The JSS category that best represents the package’s intent
	The scope of client machines the package will be applied to
	If the the FEU or FUT install options should be used
	If any policy scripts need to be run before or after the package is installed
	The date the package policy will become active
	Should the package be restricted to certain OSes?

	If you apply this checklist to each package, using it as a guide for applying metadata in Casper Admin.app and for checkpoints when creating the deployment policy in the JSS, it should help prevent common policy creation errors.

	Scripts
	Some packages need to be augmented with scripts (this is usually determined during testing). When creating a policy, you can have a script run before a particular package is installed (this could be used to remove a previously existing/older version of an application before installing a new version or to backup user data files before an application is installed) or a script can run after a package is installed (to launch the newly installed application, for example). The same advice for packages applies to scripts: test them on a number of machines before using them in production.

	Previous Policies
	Based on experience, I keep the previous version of a policy (N-1) as a safety. Better to have a fallback in the event a new package and policy experiences issues in production than to have to recreate past work.

	_Tools_
	GUI Tools
	JAMF Composer: Package making utility. Can generate both DMG and PKG format files.
	JAMF Casper Admin: Used to upload files to the JSS and apply metadata to those files.
	BareBones TextWrangler: Text editor that can read and write plist files.
	fernLightning fseventer: GUI tool for observing file system events as they happen. Useful for seeing which files and directories are used by an application.

	Command-Line Tools
	All are built into the OS with the exception of jamf, which is installed only on enrolled machines. See the man pages for full details.
	pkgutil: Utility to get information about installed packages and examine individual packages.
	The following command will use pkgutil to expose the contents of a flat package file so that you can examine what a package is installing in greater depth.

	pkgutil --expand [pkg file] /path/to/folder/to/expand/contents/to

	xattr: Utility to manipulate extended attributes on files and folders. xattr might be needed to remove quarantine warnings from installed files using the following:

	xattr -r -d com.apple.quarantine /path/to/files

	You can view the extended attributes on an application using the following command:
	ls -al@

	Installer: CLI version of Installer.app. Has a larger number of options than GUI version. Used in scripts to install applications from a staged package. Also used when a ChoiceChangesXML needs to be used, e.g.

	installer -pkg /Users/Shared/OfficeUpg14.3.7/Office201114.3.7Update.pkg
	-applyChoiceChangesXML /Users/Shared/OfficeUpg14.3.7/NoQuit.xml -target /

	jamf: Binary that does all of the client-side work for Casper. The jamf binary is used as a way to test packages before uploading them to the JSS using the following:
	jamf install -package [package file] -path [/to/package/file]
	-target / -feu -fut

	Install is the verb in the command string telling the jamf binary what action to do. Packages can be either .pkg or .dmg files. The -packages flag is looking for the name of the package. Path is the path to the package file location. FEU = Fill Existing Users (homes with files). FUT = Fill User Template (all newly created user homes will have files). The target is almost always the root (/) volume. Example:

	jamf install -package GoogleEarth_7.1.1888_20130924 -path /Volumes/testdisk -target / -fut -feu