Installing Packages

What is a package?

If you have been using a Mac, you will have encountered an installation package file or pkg.

Package files are used to install software and configuration files on your Mac.

Package files come in different flavors and formats, but they can be summarized to these relevant components:

  • a payload
  • installation scripts

A package file may have only a payload, only scripts, or both.

The payload is an archive of all the files that the package will install on the system. The package also contains a “bill of materials” (BOM) which lists where each file should be installed and what the file privileges or mode should be.

Installation scripts can be executed before and after the payload is installed.

Additionally, packages contain some metadata, which provides extra information about the package and its contents. They can also contain images and text files, such as license agreements that can customize the default Installer app interface.

Installer application

The most common way of installing a package file and start its installation process, is to open it with a double-click. This opens the default application for the pkg extension: Installer. The Installer app can be found in /System/Library/CoreServices/. However, you rarely need to open it directly. It is usually started indirectly by opening a package file.

After launch, the Installer app presents different panels to the user. The exact order and content of the panels depends on what the developer of the package configured. At the very least, it will show:

  • a short introduction
  • prompt to authenticate for administrative privileges
  • a progress bar of the installation
  • whether the installation succeeded or failed

A package may also show:

  • a custom background image
  • a detailed introduction
  • a license agreement that needs to be accepted
  • alternative installation location
  • options to select certain subsets of files and apps (components)
  • more custom steps implemented by the developer

Installer app can also list the contents of a package file without installing it first. You can choose ‘Show Files…’ (⌘I) from the ‘File’ menu to get a list of files in the payload. This list can be very extensive and there is a search field to filter the list.

If you want to see more than just the progress bar during the installation, you can select “Installer Log” from the “Window” menu (⌘L) and then increase the output to “Show all Errors and Logs” (⌘3).

You can also review the installation log afterwards, by opening the Console application from Utilities and choosing “install.log” under “Log Reports.” You can also look at /var/log/install.log directly.

This log is notoriously verbose. There will be many entries for each installation and some related system services like software update will log here, too.

Security

Packages can place files and executables in privileged locations in the file system. When you open a package file with the installer application, it will usually prompt for administrator privileges.

In the early days of Mac OS X, package installers had no limitations at all. However, these days, digital security and privacy are important features and criteria for platforms and Apple has implemented several features in macOS which set strong limits on what third-party package installers can do.

Most importantly, System Integrity Protection (SIP, introduced in OS X Yosemite 10.11) and the Signed System Volume (introduced in macOS Catalina 10.15) prevent third-party packages from affecting system files.

Even with these protections in place, packages still provide many options for abuse. Packages are very useful to install legitimate software but can also be used to install and persist malicious tools.

File Quarantine

File quarantine does not directly limit the abilities of package installers, but it is important to understand how it works together with other security features in macOS.

Quarantine flags were introduced in Mac OS X as early as version 10.4 (Tiger) but were not actually used for much until later in 10.5 (Leopard).

When a file arrives on your Mac from an external source, such as a download in a web browser, an email attachment, or an external drive, the process that downloads or copies generally adds a quarantine flag. The quarantine flag is added in an extended attribute to the file.

Note: the examples here reference desktoppr-0.5-218.pkg, the installer for a open source command line tool I wrote. You can download its installer pkg from the GitHub repository. The version and build number might be different.

After the download, you can see some of the metadata added to the download the Finder info window. Select the downloaded pkg file and choose ‘Get Info’ (⌘I) from the context or ‘File’ Menu. In the Info window that appears, you need to expand the ‘More Info’ section, where you will see the URL it was downloaded from. There might be more than one URL if the browser was redirected.

You can get more information in the command line using the xattr command line tool: (xattr stands for ‘extended attribute’, it is often pronounced like ‘shatter’)

> xattr desktoppr-0.5-218.pkg         
com.apple.metadata:kMDItemDownloadedDate
com.apple.metadata:kMDItemWhereFroms
com.apple.quarantine

The quarantine flag has the attribute name com.apple.quarantine. You can also use xattr to show the contents of the extended attribute:

> xattr -p com.apple.quarantine desktoppr-0.5-218.pkg
0083;6842fcbe;Safari;A2964F09-ACDF-430F-8CFF-48BD75C464CD

The contents are (in order, separated by semi-colons):

  • a hexadecimal flag number: always 0083
  • a hexadecimal timestamp: e.g. 6842fcbe
  • the process that created the file: e.g. Safari
  • a universal identifier (UUID)

You can convert the hexadecimal timestamp into a human readable time with

> date -jf %s $((16#6842fcbe)) 
Fri Jun  6 16:35:42 CEST 2025

There are two more extended attributes attached to the downloaded file that are interesting. The awkwardly named com.apple.metadata:kMDItemDownloadedDate and com.apple.metadata:kMDItemWhereFroms contain the download date and the web addresses the file was downloaded from respectively. When you look at them withxattr, you see the data is stored in a binary property list format.

> xattr -p com.apple.metadata:kMDItemDownloadedDate desktoppr-0.5-218.pkg
bplist00?3A????r

To show this in a human readable format, you have to pipe the output through xxd and plutil:

> xattr -x -p com.apple.metadata:kMDItemDownloadedDate desktoppr-0.5-218.pkg | xxd -r -p | plutil -p -
[
  0 => 2025-06-06 14:35:42 +0000
]

The name of the extended attribute gives us a hint that the information is also accessible through the file’s metadata, which is a bit easier:

> mdls -name kMDItemDownloadedDate desktoppr-0.5-218.pkg
kMDItemDownloadedDate = (
    "2025-06-06 14:35:42 +0000"
)

The named kMDItemWhereFroms attribute contains the URLs the file was downloaded from. It might be more than one URL because of redirections.

The URLs for GitHub downloads tend to be very long. After manually downloading Firefox, I see these URLs:

> mdls -name kMDItemWhereFroms Firefox\ 139.0.1.dmg 
kMDItemWhereFroms = (
    "https://download-installer.cdn.mozilla.net/pub/firefox/releases/139.0.1/mac/en-US/Firefox%20139.0.1.dmg",
    "https://www.mozilla.org/"
)

It is important to remember that not all processes add quarantine flags to downloaded or copied files. As a general rule, applications with a user interface add quarantine files and command line tools and background processes do not. But there may be exceptions either way.

For example, when you download a file using the curl command line tool, it will have no quarantine flag or other metadata extended attributes. This is might be exploited by malicious software.

The quarantine flag serves as a signal to the system that this file or archive needs to be checked before opening or running. The part of the system that performs this check is called Gatekeeper.

Gatekeeper

Gatekeeper was introduced to macOS in OS X Lion (10.7) in 2011. Gatekeeper will verify the integrity, signature and notarization status of an app or executable before opening it.

A package installer file can be:

  • not signed at all
  • signed, but not notarized
  • signed and notarized

Gatekeeper works somewhat differently for installer packages compared to applications that you download in disk image (dmg) or other archive formats (e.g. zip). When you copy an application out of a disk image into the Applications folder or unarchive it from an archive, the system transfers the quarantine flag and metadata to the application bundle on the local disk. When you then open the app for the first time, the presence of the quarantine flag signals Gatekeeper to verify the integrity of the application using the signature and verify the notarization status. You can see the dialogs the system might present in this Apple support document.

The signature verifies the integrity and the source of an application or installer package. With an intact signature, you can be certain the package file has not been modified since it was signed. If the signature uses an Apple Developer ID, you can be fairly certain that the package was signed by that developer, or someone from that organization. There have been cases where Apple Developer ID certificates were stolen, but Apple will usually invalidate those fairly quickly.

Notarization is an extra step where the developer uploads the signed package file to Apple’s notarization servers. Apple then scans the package for certain security features and whether known malware signatures are present. Apple then adds the package file’s hash to their notarization database. The developer can also ‘staple a ticket’ to the package file, so that Gatekeeper doesn’t have to reach out to Apple’s servers on the check.

When the Gatekeeper verification of the signature and notarization status succeeds, the user gets a prompt to confirm that they want to launch the application they just downloaded.

When either verification fails, most commonly because the app is not notarized, the user gets a different, quite scary, prompt, stating that the system cannot verify the package is free of malware. You will get the same dialog when the package is not signed at all.

While generally, all software developers should sign and notarize their packages, this is not always the case. Open source projects, often have neither the financial nor logistical means to obtain an Apple Developer account, which provides the required Apple Developer ID certificates.

Bypassing Gatekeeper

Before you choose to install a package file which is not validly signed or notarized, you should first be certain the source is trustworthy. Then you should probably inspect the package using the tools in this post to verify that it only installs what it is supposed to, before actually installing it.

After attempting to open the pkg file with the Installer app by double-clicking and receiving the dialog that it could not be verified, click ‘Done.’ Then navigate to the ‘Privacy & Security’ pane in System Settings. Under the ‘Security’ section, you will see a message that the package ‘was blocked to protect your Mac’ with a button to ‘Open Anyway.’

This extra option will disappear after a few minutes.

You can also remove the quarantine flag using the command line.

> xattr -d com.apple.quarantine desktoppr-0.1.pkg

Without the quarantine flag, the Gatekeeper verification will not be triggered when the file is opened.

Packages installed by a device management service are not checked by Gatekeeper and do not need to be notarized. With some services, the packages may need to be signed, but not necessarily with an Apple Developer ID. Consult the documentation of your device management service for details.

Installer command line tool

You can also install package files from the command line using the installer tool.

To install a package file on the current system volume, use the installer command like this

> sudo installer -package desktoppr-0.5-218.pkg -target /

There are shorter flags for both these options:

> sudo installer -pkg desktoppr-0.5-218.pkg -tgt /

Installing a package with the installer command will not enforce a restart or logout, whether the package requires one or not. You will have to perform or schedule the reboot manually.

Installing with installer will also not trigger GateKeeper checks, whether the quarantine flag is set or not.

The -verbose flag will increase the output of the installer tool which can help when you need to analyze problems. The installer process will also log to /var/log/install.log so you can also monitor or review the installation log in the Console app.

Apple Platform updates for July 2025

I usually post this collection of links as part of the weekly MacAdmins.news summary, but that is currently on a slower bi-weekly “Summer Camp” schedule. So I am posting this here for a change and will link in the issue next week.

The dot-six updates, as is common are mostly bug fixes and security patches. The enterprise notes have a bit of relevant information, especially for macOS 15.6. (More so than the general “What’s new in” articles.

And with this, we say good-bye to macOS Ventura 13. Barring some terrible security vulnerability, this will be the last update for the macOS release with the poppy. (One of my favorite default desktop pictures.)

macOS

iOS and iPadOS

Other Platforms

Inspecting Packages

The macOS installation process installs a pkg file with root credentials. Because of this high level of privileges, it is essential for a Mac system administrator or security expert to be able to inspect the files and scripts.

macOS comes with several tools to work with package files. Most of them are command line tools. pkgutil lets you examine a pkg file and its contents before the actual installation. It also lets you inspect which packages and files have already been installed on a given system.

Installed Packages

You can use the pkgutil command to list packages that have been installed on the system.

$ pkgutil --pkgs

This will list all packages that have been installed on the system. On a freshly installed macOS 15.5 system the list is very short:

com.apple.files.data-template

But depending on the version of macOS and how long the system has been running the list may have hundreds of entries. You can use grep to filter the output, but pkgutil has its own filter option: (I ran this on a system with a few more things installed.)

> pkgutil --pkgs='com.scriptingosx.*'
com.scriptingosx.Installomator
com.scriptingosx.swift-prefs-tools
com.scriptingosx.utiluti
com.scriptingosx.desktoppr

Note that you need to quote the search term otherwise the shell will attempt to expand the wildcard.

Information for an Installed Package

pkgutil --pkgs lists the identifiers of the packages. Identifiers are chosen by developer, but should generally follow the “reverse DNS notation” scheme.

When properly used, identifiers allow the installer process to distinguish between new installations, upgrades and packages that have already been installed. There is another piece of information necessary to determine this and that is the version of a package. To get the version and other information on a specific package run

> pkgutil --info com.scriptingosx.desktoppr 
package-id: com.scriptingosx.desktoppr
version: 0.5-218
volume: /
location: 
install-time: 1720421876

The install time is logged in epoch time (seconds since January 1, 1970). To convert it into something readable by humans you can use the date command:

> date -r 1720421876
Mon Jul  8 08:57:56 CEST 2024

Note: in earlier versions of Mac OS X the information on installed packages were stored in individual files called receipts. While the information is now stored in a database, the data is still referred to as a receipt.

Listing the Files a Package Installed

The --files option lists all the files that were installed by a package. The file paths are given relative to the packages install-location. Usually, but not always, the install location is the root of the file system/.

> pkgutil --files com.scriptingosx.desktoppr
usr
usr/local
usr/local/bin
usr/local/bin/desktoppr

The --file-info option does the reverse and looks up which package installed a specific file. If a file was placed there by multiple packages with different package identifiers, you will get a list.

> pkgutil --file-info /usr/local/bin/desktoppr
volume: /
path: /usr/local/bin/desktoppr

pkgid: com.scriptingosx.desktoppr
pkg-version: 0.5-218
install-time: 1720421876
uid: 0
gid: 0
mode: 100755

The installer receipt remembers the file’s owner (uid, 0 is root) and group (gid, 0 is wheel) and the permission mode that was stored in the package. Along with the actual files, the installer package also contains the owner, group, and mode (access privileges) for each file.

The metadata in the receipt may not match the file’s metadata on the disk. This indicates that the file was changed since installation. But it is difficult, if not impossible to know whether the change was intentional, accidental or even malicious. You will have to use your good judgement.

Unfortunately, some developers do not know or understand that installation packages also set the metadata for payload files and you often see changes to the owner, group and file mode applied in a postinstall script. When evaluating whether an installed file has been tampered with after installation, it is necessary to check postinstall scripts for such actions.

When a file was not installed by a package installer the --file-info option will return the path and volume, but no package information:

> pkgutil --file-info /Applications/Notes.app       
volume: /
path: /Applications/Notes.app

This is also the case for files that were copied, moved or created by a package’s preinstall or postinstall script. You only get the package data for files that were placed from a package’s payload.

Forgetting an installed package

The installation system on macOS uses the package identifier and version in the receipt to determine if an installation is new to the system, a different or new version of an already installed package, or a re-installation of a package of the same version. The behavior of the installation may change between theses scenarios.

You may notice that when you delete files or apps that were installed from a package and then re-install the same version of the package, that the files may not re-appear on the system. This happens often when you are testing an installation workflow over and over again on the same system.

You can use pkgutil --forget to remove the receipt of a package from the system. The --forget option will not delete any files that were installed on the system. All it removes is the installation receipt. If you then install the same package again, the system will consider it a fresh, new installation and the payload should be installed correctly.

Uninstalling

The macOS installation system does not have an option to uninstall or remove files and apps that were installed with an installation package. You can get a list of files that were installed from the package payload or the receipt. This will be a good starting point, but an app or tool might also create daemons, agents, preferences, configuration files, and other resources in various places across the file system. All these files weren’t part of the package payload and wouldn’t be tracked in the receipt. You will have to inspect all of these and judge whether you need to remove them, as well. Daemon and agents will need to be properly unloaded and quit before deleting their files.

Once you have built a script that performs the un-installation to your satisfaction, you should also run pkgutil --forget and remove the record of the package being installed to ensure a future re-installation will run smoothly.

Inspecting Package Payload Files

Sometimes you want to see what a package file will do without actually installing it. pkgutil has some options for that, too.

Our example file will be the installer I provide for one of my projects: desktoppr. Desktoppr is a command line tool to set the desktop picture or wallpaper on macOS.

You don’t have to actually install desktoppr to inspect the pkg. Though if you want to, you can install the pkg and use pkgutil to determine what it installed and then delete that single file later.

You can download the latest package installer file for desktoppr from the ‘Releases’ section on the GitHub repository. Note that, like many other projects, desktoppr has a pkg and a zip download. For this, we are only interesting in the pkg file.

The file command reports a pkg file is a xar archive:

$ file ~/Downloads/desktoppr-0.5-218.pkg
/Users/armin/Downloads/desktoppr-0.5-218.pkg: xar archive compressed TOC: 4389, SHA-1 checksum

(The exact output of this command may vary depending on your version of macOS and the version of the pkg.)

Packages are compressed into a single archive file. This ‘flat’ package format was introduced in Mac OS X Leopard 10.5 in 2007, replacing and deprecating the previous ‘bundle-style’ packages. Bundle-style packages were finally made defunct in macOS Sequoia 15.0 in 2024. Unless you have to support legacy Macs you should only encounter flat packages.

To expand the package, we can use pkgutil --expand

> pkgutil --expand desktoppr-0.5-218.pkg Desktoppr
> ls Desktoppr
Distribution  desktoppr.pkg

This will create a folder named Desktoppr with the expanded contents of the package file.

Inside this folder, you will see a file named Distribution. Open this file with a text editor. (open -e Desktoppr/Distribution will open the file in TextEdit if you don’t have another editor available.)

This XML file contains the metadata for the installer process. The most interesting elements are pkg-ref, which has the version and the identifier for the package and the components. It also shows the options or components that are available from the user in the Installer application.

There is a sub-folder called desktoppr.pkg inside the expanded folder. The pkgutil --expand command has already expanded this component, so we don’t need to expand it again.

> ls Desktoppr/desktoppr.pkg/
Bom         PackageInfo Payload

Note: When you are inspecting the expanded file structure in Finder, it will show this subdirectory with the package icon. The folder name ends with .pkg which Finder erroneously interprets as a file extension for a bundle-style installation package. If you want to see the contents of this folder in Finder, choose ‘Show Package Contents’ from the context menu.

Inside the sub-directory or component, you will find three more files.

PackageInfo is another XML file with metadata on the component. The most relevant information in here is right in the first pkg-info tag, which has attributes for identifier, version and install-location.

The Payload file is another archive with the actual files inside it. If you wanted to extract the files manually you can do so with:

> tar xvf Desktoppr/desktoppr.pkg/Payload
x .
x ./usr
x ./usr/local
x ./usr/local/bin
x ./usr/local/bin/desktoppr

The folder structure of the payload is relative to the package’s install-location.

Bill of Materials

The last file is called Bom which is short for ‘Bill of material’. It contains an entry for each file in the Payload with additional metadata: owner, group, and file mode (access privileges). It is stored in a binary format, so it cannot be read with a text editor, but you can read the content with the lsbom command.

> lsbom Desktoppr/desktoppr.pkg/Bom
.    40755   0/0
./usr    40755   0/0
./usr/local    40755   0/0
./usr/local/bin    40755   0/0
./usr/local/bin/desktoppr    100755  0/0 271792  550451430

This will output one line per item in the package. The entries or columns per line are: path, file mode, owner id/group id, file size and a CRC 32-bit checksum (only for files).

There are many options to control the output of the lsbom command. You can find them all in its man page.

Since the bill of material (Bom) is very interesting pkgutil provides a shortcut to get it without having to expand the entire pkg file.

> pkgutil --bom desktoppr-0.5-218.pkg
/tmp/desktoppr-0.5-218.pkg.boms.vVNvMz/desktoppr.pkg/Bom

This command will extract the Bom into a temporary file and output the path. You will use this most commonly together with lsbom.

pkgutil also has a --payload-files option:

pkgutil --payload-files desktoppr-0.5-218.pkg 
.
./usr
./usr/local
./usr/local/bin
./usr/local/bin/desktoppr

This output shows only the file path. If you require more information, use the --bom option to export the Bom file and use lsbom.

More Complex Packages

The desktoppr installation package is a very simple package. It installs a single binary file.

For a slightly more complex package, you can download the installer pkg for Setup Manager. Setup Manager is an enrollment tool that works with Jamf Pro and Jamf Connect.

Again, you do not have to actually run the installer to inspect. In this case, the tool will only work on a Mac managed with a Jamf management server at enrollment. Nevertheless inspecting this package will be instructive.

First, use pkgutil to list the payload files.

> pkgutil --payload-files Setup\ Manager-1.3.1-610.pkg
.
./Library
./Library/LaunchAgents
./Library/LaunchAgents/com.jamf.setupmanager.loginwindow.plist
./Library/LaunchDaemons
./Library/LaunchDaemons/com.jamf.setupmanager.plist
./Library/LaunchDaemons/com.jamf.setupmanager.finished.plist
./Applications
./Applications/Utilities
./Applications/Utilities/Setup Manager.app

There are more files that are listed, but they are all files and folders in the Setup Manager.app bundle. This package installs two LaunchDaemons and a LaunchAgent, as well as the Setup Manager application in /Applications/Utilities

To learn more, expand the package file with pkgutil:

> pkgutil --expand Setup\ Manager-1.3.1-610.pkg SetupManager
> ls SetupManager                     
Distribution      Resources         Setup Manager.pkg
> ls SetupManager/Resources        
License.rtf Readme.rtf

We see a new subfolder named Resources which contains two rich text files. These are shown in the respective panes when the pkg file is opened with the Installer application. You can double-click the Setup Manager pkg to open it in the Installer application and see the two panes. You don’t need to follow through with the installation.

When we dig further into the expanded Setup Manager we see another folder we did not have before:

ls SetupManager/Setup\ Manager.pkg/
Bom PackageInfo Payload Scripts
ls SetupManager/Setup\ Manager.pkg/Scripts
postinstall preinstall

The Scripts folder in the component contains two scripts: preinstall and postinstall. The installation process will run these scripts before and after the payload files are installed on the system.

When you open the script files in a text editor, you can see that these unload and load the LaunchAgents and Daemons in the payload.

You can use pkgutil and lsbom to inspect all kinds of packages. If you want to practice, the Microsoft installers are a very good exercise.

Component Packages

There is a simpler type of packages. As an example, download the installer pkg for an early version of desktoppr.

When you expand this pkg file with pkgutil, you will see no Distribution XML file or sub-component folders.

$ pkgutil --expand desktoppr-0.3.pkg Desktoppr0.3
ls Desktoppr0.3/
Bom PackageInfo Payload

Instead you see the three files we saw earlier in the component subfolder of the main pkg: Bom, PackageInfo, and Payload. Nevertheless, if you were to install this package, it would work just fine and install its payload.

This is a component package. Generally, component packages are built as an intermediate step to assemble the distribution package format we saw earlier. Nevertheless, component package files will work fine on their own, as well.

Distribution Packages, Product Archives, and Component Packages

Most of the pkg files you will encounter are distribution packages. Distribution packages do not have a payload or installation scripts of their own. Distribution packages contain one or more components. Each component will have a payload and (possibly) installation scripts.

Distribution packages are wrappers for their components and can have some extra data, such as the License and ReadMe file we saw earlier.

Apple’s developer documentation often refers to “product archives.” Product Archives are a different name for distribution packages with a specific set of metadata. Most relevantly, product archives have an identifier and version set.

Distribution packages and product archives allow the developer to customize the interactive installation process in the Installer application. Product archives are also a requirement for publishing in the Mac App Store. For these reasons, product archives are the recommended choice for developers to distribute their software.

Component packages already provide the most relevant feature for package installers: they install files. They are quite simple to create, which makes them popular with Mac system administrators who often need to build custom installers that are installed silently from a management system. There are, however, some situations where distribution packages are required with management systems, too.

Suspicious Package

Understanding the command line tools and workflows to expand and inspect pkg files is a good exercise and an important foundation to building packages. Nevertheless, it can be tedious when all you want is to just to see the files inside or some metadata for the package.

The application ‘Suspicious Package‘ provides a powerful and useful graphical interface for inspecting installation packages and their payloads. It gives an overview of package’s metadata, including signature and notarization status. It will show a detailed graphical view of the payload, the metadata files and installations scripts. When necessary, you can preview or extract individual files for further analysis

There will still be situations where you will need pkgutil, but Suspicious Package is an indispensable tool for any Mac Admin and Mac security professional. You can download Suspicious Package for free from Mothers Ruin Software.

Updates: Setup Manager and utiluti

Setup Manager 1.3

We have released Setup Manager 1.3 today. You can see the release notes and download the pkg installer here.

Most of the changes to Setup Manager in the update do not change the workflow directly. The focus for this update was to improve logging and information provided for trouble-shooting.

With the 1.3 update, Setup Manager provides richer logging information. You will find some entries in the Setup Manager log that were not initiated by the Setup Manager workflow, but are still very relevant to troubleshooting the enrollment workflow. You can see all installation packages that are installed during the enrollment, as well as network changes. This allows an admin to see when managed App Store installations or other installations initiated from the MDM or Jamf App Installers are happening in the enrollment workflow.

These can be very helpful to determine what might be delaying or interrupting certain other installations.

When we started building the “enrollment tool we wanted to use ourselves” more than two years ago, we chose to build a full application, rather than a script-based solution which remote controls some interface. One of the immediate benefits is that we could make the user interface richer and more specialized. Localizing the app into different languages was easier, too. Setup Manager adds Polish localization, bringing the total number of languages to ten!

(We use the help of volunteers from the community to localize to other languages, if you want to help localize Setup Manager into your language, please contact me.)

There was another goal, which took a bit longer to realize.

Swift apps allow us to dive deeper into the capabilities and information available in the operating system. A full blown app is also more capable at analyzing and displaying multiple sources of information at the same time. For example, Setup Manager will display a big warning when the battery level drops below a critical threshold.

These kinds of workflows and user interfaces would be nearly impossible or, at the very least, extremely complex to build and maintain with shell scripts. In this case, Setup Manager is monitoring and parsing other log files and summarizing them down to some important events in the background, while it is working through its main purpose of running through the action list from the profile.

This feature will not be seen by most users or even techs who are sitting in front of the Mac, waiting for the base installation to finish. But when you are trouble shooting problems during your enrollment workflow, these extra log entries can be very insightful. Even during testing, it unveiled some surprises in our testing environments.

We hope you like the new features. But, we are also not done yet and have plenty more ideas planned for Setup Manager!

utiluti 1.2

Since we are talking updates, I have also released an update to my CLI tool to set default apps for urls and file types (uniform type identifiers/UTI). utiluti 1.2 adds a manage verb which can read a list of default app assignments from plist files or a configuration profile. You can see the documentation for the new manage verb here and download the latest pkg installer here.

This allows you to define lists of default apps and push them with your device management system. Then you can run utiluti from a script in the same management system. This should greatly simplify managing default apps.

Note, that while you can set the default browser with utiluti, whether you are using the manage option or not, the system will prompt the user to confirm the new default browser. For this use case, you will want to put the utiluti command in a context where the user is prepared and ready for that extra dialog (such as a Self Service app). There are other tools, such as Graham Gilbert’s make-default CLI tool, which bypass the system dialog. In my experience, tools like this work well in fairly clean setup and require a logout or reboot after the change. This might fit your workflow, but you need to test.

I hope utiluti will find a place in your MacAdmin’s toolbox!

Installomator v10.8

Further chipping away at the backlog of new and updated with merged 200 PRs merged or closed.

The new PR templates and automations are proving to be a big help! Many thanks Bart for working on these and all the maintainers for staying on top of most things.

This release brings Installomator to 1025 (!) labels!

Many thanks to all the contributors, this tool wouldn’t exist without you!

You can find the detailed release notes and the pkg on the repo!

New tool: utiluti sets default apps

A while back I wrote a post on the Jamf Tech Thoughts blog about managing the default browser on macOS. In that post I introduced a script using JXA to set the default application for a given url scheme. (like http, mailto, ssh etc.) The beauty of using JXA/osascript is that it doesn’t require the installation of an extra tool.

However, there was a follow-up comment asking about default apps for file types, i.e. which app will open PDF files or files with the .sh file extension. Unfortunately, Apple has not bridged those AppKit APIs to AppleScript/JXA, which means it is not possible to use them in a script without dependencies.

Back then, I started working on a command line tool which uses those APIs. I didn’t really plan to publish it, since there were established tools, like duti, cdef and SwiftDefaultApp that provided the functionality. It was a chance to experiment and learn more about Swift Argument Parser. Then life and work happened and other projects required more attention.

A recent discussion on the Mac Admins Slack reminded me of this. Also, none of the above mentioned tools have been updated in the past years. As far as I can tell, none of them have been compiled for the Apple silicon platform. They don’t provide installation pkgs either, which complicates their distribution in a managed deployment.

So, I dusted off the project, cleaned it up a bit, and added a ReadMe file and a signed and notarized installation pkg. The tool is called utiluti (I am a bit proud of that name).

You can use utiluti to set the default app for an url scheme:

$ utiluti url set mailto com.microsoft.Outlook
set com.microsoft.Outlook for mailto

or to set the default app to open a uniform type identifier (UTI):

$ utiluti type set public.plain-text com.barebones.bbedit
set com.barebones.bbedit for public.plain-text

There are bunch of other options, you can read the details in the ReadMe or in the command line with utiluti help.

The functionality is quite basic, but please provide feedback if there are features you’d like to have added.

Installomator v10.7

Chipping away at the backlog of PRs and issue, we have released a new version of Installomator today.

Main focus was on releasing a whole bunch of new and updated labels. But the maintainer team has also started work on implementing to templates for issues and PRs and some automation for testing. This should help a lot with the effort to keep up with new issues and PRs going forward.

Many thanks to all the contributors and maintainers for the hard work that went into this!

You can find [the detailed release notes and the downloads on the repo!](https://github.com/Installomator/Installomator/releases/tag/v10.7)

Run a script when Setup Manager is finished

You may have heard, we built an enrollment tool called Setup Manager for Jamf Pro and Jamf School.

As with any new tool, there are some things that it doesn’t do yet and there are some conflicts with other software that we hadn’t anticipated.

We are working on these things, but it takes time. Until then, I thought it might be useful if there were a way to trigger you own scripts when Setup Manager is finished with its workflow. This wasn’t too hard to put together and I can already see a few useful applications.

How it works

You can use LaunchDaemons to run your own scripts and tools in the background. There are many different triggers you can use to control when your LaunchDaemon launches. One option is a WatchPath which triggers when a file at a certain path is created, deleted or modified.

Setup Manager creates a flag file at /private/var/db/.JamfSetupEnrollmentDone when it completes successfully. We can use this file as a watch path to launch our own script: setupManagerFinished.sh.

In the script, we first set a few useful variables. Since the WatchPath LaunchDaemon triggers on creation, deletion and modification, the script checks first whether the flag file exists, otherwise it just exits without doing anything.

Then the script waits for the jamf binary to not be running anymore. With Jamf Pro, when Setup Manager finishes up, it creates the flag file and then runs its final recon/inventory update. It has to do it in this order, so that an extension attribute that is checking for the flag file gets updated correctly. That means that our script will be triggered before Setup Manager is actually really done. But we can be fairly sure that when the jamf process is done, then Setup Manager has really finished its workflow.

Setup Manager might be still displaying its UI here, but the work is done. (If you want to defer launching until Setup Manager itself quits, you can replace jamf with "Setup Manager" (quotes are important) in line 30.)

Then, we get to the point where we run what we actually want to do. In the sample project, the script runs the jamf binary with a custom trigger. All policies in scope with that custom trigger will be executed. You can even attach a restart action to the last of those policies to force a reboot at this point.

SetupManager and this LaunchDaemon can run with Jamf School, as well. In that case, you wouldn’t run the jamf binary since that is exclusive to Jamf Pro. But you can modify the script to run other commands here to finish the setup.

Chicken, meet egg

You can do additional installations using Installomator, especially for tools that might interfere with Setup Manager. You can send notifications to Slack or Teams with data from the completed Setup Manager workflow.

You can also force a restart here with the shutdown -r +5s command. (The five second delay gives the LaunchDaemon script a chance to clean up and exit.)

Authentication tools, like Jamf Connect or XCreds, need to restart the login window so that their software can load correctly. If you are using the option to run Setup Manager at the login window, this will quit and then restart Setup Manager, too.

Some tools and apps have installation workflows that simply don’t work well with Setup Manager for other reasons.

That means you want to avoid installing these tools with Setup Manager directly, but you can install them after Setup Manager is done.

With this LaunchDaemon, you can run all kinds of additional workflows and install troublesome tools, either with a Jamf Pro policy or Installomator.

Usage

Download the repo and adapt the setupManagerFinished.sh script to your needs. The code you want to adapt is in lines 39 through 47.

The default script triggers a custom policy trigger (setup_manager_finished, defined in line 10)

The buildSetupManagerFinishedPkg.sh script will assemble the LaunchDaemon plist, the script and the installation scripts into a pkg.

You will have to adapt the name of the certificate you use to sign the pkg in line 20. If you do not have a signing certificate, you can set signature="" and the script will build an un-signed pkg. You need a signed installer pkg when you want to add it to the Jamf Pro Prestage or install it with Jamf School. When the pkg is not signed, you can still install it with a Jamf Pro policy with a Setup Manager action. As long as it is installed before Setup Manager finishes, it will trigger when the flag file gets created.

Conclusion

You can find the code on the repository. I am curious what workflows y’all are going to build with this! Let us know in the Mac Admins Slack in the #jamf-setup-manager channel!

Installomator v10.6

It is that time again, we have released a new version of Installomator!

Many thanks to all the maintainers and contributors!

It has been quite a while since we published a release and there was quite a backlog. In some ways, Installomator is a victim of its own success. It is quite easy to create a new label and many contributors are doing that. It is also easy to provide an update to a broken label and while many contributors are doing that, there are fewer of them.

This means that we are accumulating a lot of stale and broken labels. Since there is now way for us to gather information on which labels are actually being used and how much, we end up with lot of turnover.

The team of maintainers has some ideas to tackle some of these problems with automation, but human curation will have to remain a step all along the way.

You can get the latest version of Installomator on the repo or download the installer pkg from here.