Creating a Custom Installer for Mac (PKG Package)

While Identity Finder is distributed from the IdentityFinder.com website as a dmg, modification to the dmg or application bundle contained therein is not supported. Any organization using the Mac client must create and deploy a custom Installer Package that can include a custom xml file, license file, and other supplementary files as well as configure the endpoint service application.

The only supported method for creating a custom Installer Package is to use the Identity Finder Client Custom PKG Builder (PKGBuilder) application referenced by and attached to this article. This application uses pkgbuild, productbuild, and productsign, which are all included with Mac OS.

Note: Mac clients prior to version 8 cannot read the package format created by this tool. Therefore:

Packages created with this tool can be used for new installations of version 8 of the Mac client.
Packages created with this tool can be used for manual upgrades of any version of existing client installations.
Packages created with this tool can be used when upgrading via the console if the version of the client already deployed is 8.0 or later.
If the version of the client already deployed is 7.2 or earlier, upgrades via the console cannot use packages created with this tool. In that case, a package with a client of 8.0 or later must be created using the scripts method and detailed in the following KB article:
- Creating a Custom Installer for Mac (PackageMaker Package) - v5.0-7.2

Note: The package must be created on a system running Mac OS X 10.7 or later. Once a package is created, it may be installed on any operating system version supported by the version of the application being installed.

Note: Configuring HTTPS/SSL is outside the scope of this article. If SSL is to be utilized, it is necessary to ensure that the required files and settings are available prior to building the package. For additional information, please refer to the article:

Enabling SSL communication between Endpoint for Mac and the Console

Note: This information only applies to Identity Finder for Mac v8.0 and later. For reference or configuring/troubleshooting an earlier installation package, refer to the appropriate KB:

This article contains the following sections:

Obtaining the Installation Files

To begin the process, download the PKGBuilder application, Identity Finder application, and client/console communication configuration file.

Download the file IdentityFinderClientCustomPKGBuilder.zip containing the PKGBuilder application.
Download the most recent version of the Mac client software, IdentityFinderSetup.dmg, from the Customer Portal.
Download your license file, identityfinder.lic, from the Customer Portal.
Open a web browser, navigate to http://consoleserver/Services where consoleserver is the name or IP address of the console and click on the appropriate link for Mac version 7.1 and newer to save the com.identityfinder.macedition.xml file to the local client.

Using PKGBuilder to automatically create a PKG

The PKGBuilder application provides a GUI to easily customize the installation package to, for example, include a license file and specify settings.

To open the PKGBuilder, follow these steps:

Navigate to the folder where you downloaded IdentityFinderClientCustomPKGBuilder.zip
Extract Identity Finder Client Custom PKG Builder.app from the zip to a temporary location
Drag the Identity Finder Client Custom PKG Builder app icon into the Applications folder to install the application
Launch the application from your Applications folder

To create a custom installer package, follow these steps:

Complete the relevant fields in the main window of the PKGBuilder GUI (details below image):
- Source dmg – (Required) The full path to IdentityFinderMacSetup.dmg. The setup application can be obtained by logging into the Customer Portal. The button labeled, "Download Client" will open the default web browser to the portal login page.
- Output location – (Required) The full path in which to output the resulting customized PKG file. Note: The output file will be named IdentityFinderX.X.X.X.zip where X.X.X.X is the current version number - for example IdentityFinder8.0.0.0.zip. Inside of that zip is IdentityFinder.pkg and an Info.plist file. The entire zip file is used for uploading to Console for use when updating.
- License file – The full path to the identityfinder.lic file.
- XML Settings file – The full path to the com.identityfinder.macedition.xml settings file obtained from the console.
- User Defaults file – The full path to the com.identityfinder.macedition.firstrun.xml settings file. This allows the inclusion of a system FirstRun configuration file. If the Initialization\Configuration\AlwaysUseFirstRun setting is set to "Always reset settings" (1) or Initialization\Configuration\FirstRun setting is set to “True” in a system policy applied to the endpoint and a User Default policy also exists, the settings in the xml will be merged with the settings from a User Default policy (if a setting exists in both locations, the value in the User Default policy will be used). The User Defaults file is not required to build a PKG. It is optional. It allows the inclusion of a system FirstRun configuration file which allows you to set defaults that are different than the application defaults, allows the user to change those settings in the UI, but then resets those custom defaults each time Identity Finder is launched. To create a User Defaults file perform the following steps:
- Use existing certificate from System Keychain - This is necessary only if you are using HTTPS/SSL and the console is using a private or self-signed certificate that is already in the System Keychain of the endpoint systems. In that case, check this box to have the PKGBuilder automatically set the Console\caUseKeychain setting in the xml settings file. For more detailed information, refer to Enabling SSL Communications between Mac clients and the Enterprise console.
- Certificate file – This is necessary only if you are using HTTPS/SSL and the console is using a private or self-signed certificate that is not already in the System Keychain of the endpoint systems. The PKGBuilder will automatically set the Console\caPath setting. For more detailed information, refer to Enabling SSL Communications between Mac clients and the Enterprise console.
- Copy Certificate File to System Keychain - If a certificate is specified in the Certificate file field above, check this setting to automatically add the certificate to the System Keychain and have the PKGBuilder automatically set the Console\caUseKeychain setting.
- Install Endpoint Service - Specify whether or not the Identity Finder Endpoint Service should be installed. When using the client with the enterprise console, this box must be checked or communication with the console will fail.
- Signing ID – Enter your Apple Developer Code Signing ID if the machines on which the PKG file will be installed require all installation packages to have a valid digital signature.
Configure any desired additional, advanced settings by clicking the Advanced button on the toolbar. When the Advanced Options dialog is displayed, the default value for each property is displayed.
- Welcome message file – The full path to a custom Welcome message. This message will be integrated into the installer GUI and will automatically display when running the installer. The welcome message file must be in Rich Text format and named Welcome.rtf.
- ReadMe message file - The full path to a custom ReadMe message. This message will be integrated into the installer GUI and will automatically display when running the installer. The ReadMe message file must be in Rich Text format and named ReadMe.rtf.
- Install on root volume only – By default, the application will be installed on the root volume. If you want to install somewhere else, for example another partition on your hard drive, unchecking this option will allow you to select another installation location in the installer GUI.
- Disable App Nap - By default, App Nap will be enabled for the application. To disable App Name for the SDM Endpoint application, check this box. App Nap is a feature of Mac OS and when it is enabled, the operating system may pause the SDM Endpoint application when it is hidden from view and reduce the resources available to the application. This behavior will slow the search process when the application is minimized or running in the background. Disabling App Nap will allow the application to continue running normally even while it is minimized or in the background.
- Upgrade from Identity Finder to Spirion - By default, the PKG file created is for new installations or upgrades from version 10.0.2 or higher endpoints. Enable this option to build a PKG that supports upgrading from Identity Finder version 9 or earlier endpoints or Spirion version 10.0.1. If the installed version is 10.0.2 or higher then leave this option disabled.
- EndpointService binary name - The name of the Identity Finder Endpoint Service. This name will be viewable from within Activity Monitor. The default is EndpointService.
- UserAgent binary name - The name of the Identity Finder User Agent. This name will be viewable from within Activity Monitor. The default is UserAgent.
Click the Build Installer button. While the PKG is being built, the build log will display in a window. You can click the Log button on the toolbar to hide the window.
When the PKG is created, a dialog box will display stating the build is complete. If an error was encountered, the details will be in the Log.

Testing the Package

It is critical to test the complete package prior to deployment. Note, the PKGBuilder application must not be running when attemping to install or execute the client application.

To test the installer package, complete the following steps:

Extract IdentityFinder.pkg from the zip file created by the PKGBuilder application.
Launch the IdentityFinder.pkg by copying it to a test workstation and double-clicking on it.
Complete the Identity Finder Installer and allow the installation to finish. If the pkg fails to successfully complete the installation, reference the Troubleshooting section below.
Launch the Identity Finder client. If a license file, identityfinder.lic, was included in the installer, the activation screen should not be displayed. If the activation screen is displayed then the license provided was either invalid or expired. Contact whomever provided identityfinder.lic and have them consult with the sales team to determine the licensing issue.
Run a search on the test workstation and ensure that some results are found. If the test workstation has no data on it, test data may be downloaded and placed on the system for testing purposes.
If communication with the console was part of the installer packager, wait 10 minutes after the search with results completes and the client has been closed. Log in to the console and review the results from the test run. If the results do not appear in the console, perform the appropriate troubleshooting steps to determine the issue.

Troubleshooting

There may be errors when attempting to build or install the PKG. This section will address common errors encountered as well as steps to perform if the PKG does not build or install properly.

PKG Build Failure

To address issues identified during the building of a PKG file, it is necessary to review the build errors. To review the errors, look in the Log window of the PKGBuilder. If the log window is not displayed, click the Log button on the toolbar. The error(s) preventing the build from completing will usually be displayed toward the bottom of the log and include the words error, fail, or failure. The most common errors are due to incorrect permissions on the supporting files, for example if the PKGBuilder is unable to read the license file for inclusion in the PKG. An Internet search of the error text will usually explain the issue. If you are unable to resolve the errors on your own:

Save the contents of the Log window to a text file by selecting the File menu and then selecting Save Log.
Take a screen shot of any errors that are displayed in a dialog by PKGBuilder or Mac OS.
Request assistance from the Support Team by open a support ticket.
Attach the log text file and screen shot(s), if applicable to the support ticket.

PKG Signing Error

If you receive an "Expired Certificate" error while building the PKG, in addition to verifying the the expiration date on your installer certificate, you may need to check the expiration date of your Apple Worldwide Developer Relations certificate, which is an intermediary certificate in the chain. If you experience this issue, here are the steps to correct it:

Open up Keychain Access.
Show the expired certificate by going to View > Show Expired Certificates,
Navigate to the System Keychain and delete the expired WWDR Certificate.
Download the new WWDR Certificate here and import it into your keychain.

PKG Installation Failure

To address issues identified during an PKG installation, it is necessary to review the installation errors. To review the errors, perform the following steps:

Open a Terminal window
Execute the following command:
```
open /var/log
```
When the Finder window opens, locate the following file:
```
install.log
```
Double click on install.log to view its contents

The error(s) preventing the package from installing will usually be displayed toward the bottom of the log and include the words error, fail, or failure. The most common errors are due to incorrect permissions on the folders necessary for installation. An Internet search of the error text will usually explain the issue. If the package was created only using PKGBuilder, no other edits were made, and you are unable to resolve the errors on your own:

Take a screen shot of any errors that are displayed during the installation process
Post the PKG on a publicly facing web site where the Identity Finder support team can access it for reference, if necessary
Request assistance from the Support Team by open a support ticket.
Include the link for the Support Team to download the PKG file and attach the install.log text file and screen shot(s), if applicable to the support ticket.

Note: If any edits were made to the PKG file outside of the PKGBuilder application, the installer package is not supported and our Support Team will not be able to assist with troubleshooting.

Uninstalling

If it is necessary to completely uninstall the application, download the script UninstallIDF.shattached to this article and perform the following steps:

Copy the UninstallIDF.sh script to the desktop of the Mac OS system on which the uninstall is to be performed.
Open Terminal
Execute the following command to set the current directory to the desktop:
```
cd ~/Desktop
```
Execute the following command to set the permissions on the script and make it executable:
```
chmod ugo+x UninstallIDF.sh
```
Execute the following command to begin the uninstall:
```
./UninstallIDF.sh -p
```
A password prompt should be displayed. Enter the password used to log into the Mac OS system.

Search This Blog

Mac, IOS software and hardware support