In This Article:
- What are Some of the Things I Should Know Before I Get Started
- Getting the Installation Files
- Creating the Package
- Testing the Package
- Uninstalling the Spirion Package from Mac
- Troubleshooting a Bad Package
- PKG Build Failure
- PKG Signing Error
- PKG Installation Failure
- Command Line References for Mac Installation
- Notes for Command Line Installation Use
- Additional Resources
What Are Some Things I Should Know Before I Get Started?
- NEVER upgrade your endpoints first.
- NEVER upgrade your endpoints to a higher version of Spirion than the console.
- ALWAYS build a new PKG each time you attempt to upgrade.
- ALWAYS obtain the most current license from your my Spirion portal.
- ALWAYS obtain a new clientsettings.reg file as your console location may have changed since your last upgrade.
- ALWAYS manually install the.pkg on one endpoint BEFORE pushing an update through the console or through a software distributor such as JAMF or SCCM.
- BEFORE YOU ATTEMPT TO UPGRADE check this console setting: Console\CheckInstallationLocation and set that value to 2 which will have the Client update check to see if an endpoint can be upgraded. If it cannot be upgraded at this time the installation will fail. The reason you want to enable this setting instead of the default value of 1 which will check and proceed is because allowing the upgrade to proceed with a locked file will cause an unstable upgrade. Therefore, it is best to let it fail and remediate the locked file than having an unstable upgrade.
- Endpoints AUTOMATICALLY poll into the console. You can check this in the status tab of the console. If you are sure you built your .pkg correctly and do not see the endpoint in the console STOP and contact email@example.com, provide a gathered data from the console and the endpoint and support will be happy to help you get that endpoint polling again.
- If you plan to upgrade many machines, consider staggering your upgrade process by department or in groups/tags to ensure that any issues can be handled in better timing than the chaos of upgrading a large pool of machines at once
- Double check the version of the .pkg builder before starting as different versions of the builder are supported by different endpoint versions. If you are unsure which version, you need ask support.
- The only supported method for creating an installer package is the Spririon Client Custom PKG Builder in this article.
- Only Create a Mac package on a Mac do not attempt to create it on a PC or a Linux machine.
- The PKGBuilder application must not be running when attempting to install or execute the client application.
Getting 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.
Creating the Package
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 IdentityFinder10.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:
- Create a User Default Policy with ONLY the settings that you want enabled.
- Export the policy definitions as a “Local File” policy type and name it com.identityfinder.macedition.firstrun.xml.
- Open the exported policy file in XML editor.
- Delete the first link of XML the “<PolicyData Schema=”1.0”>’
- Delete the last line of the file, the “</PolicyData>” line.
- Save the com.identityfinder.macedition.firstrun.xml.
- Additionally, you will need to modify the settings in your com.identityfinder.macedition.xml settings file which you previously obtained from the console for the “XML Settings file”:
- The Following tags should be placed in the xml settings file. In the com.identityfinder.macedition.xml you would add the following tags directly above the tag which matches the code block below #9.
- Save your com.identityfinder.macedition.xml and add it as the XML Settings file.
<Setting Name=”AlwaysUseFirstRun” Type=”Bit” Restart=”false” Multi=”false”>
<Setting Name=”FirstRun” Type=”Bit” Restart=”false” Multi=”false”>
- Use existing certificate from Systems 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 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 attempting 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.
Uninstalling the Spirion Package From Mac
If it is necessary to completely uninstall the application, download the script UninstallIDF.sh attached 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:
- 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:
- A password prompt should be displayed. Enter the password used to log into the Mac OS system.
Additionally, there are several command line switches available to use with the uninstall script:
- -h: Display a list of valid switches
- -s: Execute silently
- -y: Automatically answer "Yes" to the "Preserve user prefs? (Yes/No)" prompt
- -n: Automatically answer "No" to the "Preserve user prefs? (Yes/No)" prompt
- -p: Prompt for an administrator password (required to remove system resources and perform a full uninstall)
Troubleshooting a Bad Package
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 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 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.
The dmg that we distribute is signed by us, but once you build a PKG using our Custom Installer for Mac (PKG Package) the resulting package is not signed. You would need your own developer id/certificate to sign it.
That Signing ID field in the PKG Builder requires a valid installer Signing ID, which you can get from Apple. If you enter an invalid installer Signing ID the build will fail. If you do not have a valid Signing ID, you can leave that field blank. The following article has further details on how to sign the PKG.
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:
- When the Finder window opens, locate the following file:
- 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.
Command Line Interface Reference
All the functions and settings available via the GUI are also available via a command line interface. Please refer to the GUI section(s) above for descriptions of each setting.
"/Applications/Identity Finder Client Custom PKG Builder.app/Contents/MacOS/Identity Finder Client Custom PKG Builder" -sourceLocation "/Users/macuser/Downloads/IdentityFinderMacSetup.dmg" -outputLocation "/Users/macuser/IdentityFinderInstaller" [-licenseFilePath "/Users/macuser/Downloads/identityfinder.lic"] [-xmlSettingsFilePath "/Users/macuser/Downloads/com.identityfinder.macedition.xml"] [-useExistingCertFromSystemKeychain 1] [-sslCertFilePath “/Users/macuser/Downloads/CA.pem”] [-copySSLCertFileToSystemKeychain 1] [-installEndpointService 0] [-signingID "Acme Development, LLC"] [-welcomeFilePath "/Users/macuser/Downloads/Welcome.rtf"] [-readMeFilePath "/Users/macuser/Downloads/ReadMe.rtf"] [-installOnRootVolumeOnly 0] [-disableAppNap 1]
For example, to create an installer with the specified license, xml configuration file from console and signingID and including the endpoint service, use this command line:
"/Applications/Identity Finder Client Custom PKG Builder.app/Contents/MacOS/Identity Finder Client Custom PKG Builder" -sourceLocation "/Users/macuser/Downloads/IdentityFinderMacSetup.dmg" -outputLocation "/Users/macuser/IdentityFinderInstaller" -licenseFilePath "/Users/macuser/Downloads/identityfinder.lic" -xmlSettingsFilePath "/Users/macuser/Downloads/com.identityfinder.macedition.xml" -signingID "Acme Development, LLC"
Notes for Command Line Installation Use:
- All file paths are case sensitive, must be enclosed within quotes, and must be full, absolute paths.
- The -sourceLocation and -outputLocation switches are the only required switches (this is the same as when using the UI).
- If a full path is not provided to the -outputLocation switch, the output file will be created in the folder /Users/USERNAME/IdentityFinderInstaller.
- The Endpoint Service is installed by default when using the PKGBuilder and therefore the service will be installed if the -installEndpointService switch is not specified.
- Omitting a optional switch with a 0 or 1 as its parameter is equivalent to leaving that option as its default as shown within the GUI. For example, omitting
will leave the value as 0 or "unchecked" in the UI. Similarly, specifying
will set the -disableAppNap switch to on and App Nap will be disabled on the machine where the installer is run, while omitting the switch will set it to off and App Nap will not be modified.
- The installer build process is logged to standard output.
|Option Name||Type||Value||Default Value|
|installOnRootVolumeOnly||Boolean||0 or 1||1|
|disableAppNap||Boolean||0 or 1||0|
|disableAppNapSystemWide||Boolean||0 or 1||0|
|upgradeFromIdentityFinderToSpirion||Boolean||0 or 1||0|
|installEndpointService||Boolean||0 or 1||1|
|copySSLCertFileToSystemKeychain||Boolean||0 or 1||0|
|useExistingCertFromSystemKeychain||Boolean||0 or 1||0|
|sourceLocation||String||Quoted path to source dmg (required)|
|outputLocation||String||Quoted path to output directory for installer (required)|
|licenseFilePath||String||Quoted path to license file (optional)|
|xmlSettingsFilePath||String||Quoted path to settings file named "com.identityfinder.macedition.xml" (optional)|
|userDefaultFilePath||String||Quoted path to settings file named "com.identityfinder.macedition.firstrun.xml" (optional)|
|sslCertFilePath||String||Quoted path to SSL certificate file (optional)|
|welcomeFilePath||String||Quoted path to rtf format file containing welcome text (optional)|
|readMeFilePath||String||Quoted path to rtf format file containing read me text (optional)|
|signingID||String||The installer signing id (optional)|
|packageID||String||The package id (optional)|
|installationLocation||String||Quoted path to installation location on machine where installer is run||"/Applications"|
|epsBinaryName||String||The name of the installed EndpointService binary||"EndpointService"|
|epsBinaryName||String||The name of the installed UserAgent binary||"UserAgent"|
Mac Client Release Notes: https://support.spirion.com/hc/en-us/articles/115002050672-Mac-Client-Endpoint-Release-Notes
- SpirionClientCustomPKGBuilder.zip for version 10+ (updated 3/3/17) If upgrading from an earlier version please see the Upgrade from identity Finder to Spirion option.
- IdentityFinderClientCustomPKGBuilder.zip for version 9 (updated 1/15/16)
- IdentityFinderClientCustomPKGBuilder8.zip for version 8 (updated 8/13/15)