Skip to content

Features

Jump to bottom
Chris Lasell edited this page Apr 10, 2026 · 11 revisions

altalt# Features of Xolo

In no particular order...

Automation

Xolo exists primarily so that in-house software developers can deploy updates automatically from their build-systems either locally on their Macs, or from centralized CI/CD build systems.

Simplification and Consistency

Xolo allows for simplified manual command-line management of patch titles and versions, and related policies, groups, packages, scripts, etc., without needing direct access to Jamf Pro or the Title Editor, all while ensuring consistency in naming and deployment structure.

Package Signing

The Xolo server can be configured to automatically sign .pkg files uploaded to it, unless they are already signed with a valid signature (by you or the publisher). Doing so will use the same keychain and identity that it uses to sign the xolo-client-data.pkg.

NOTE: While it may seem insecure to allow the server to sign pkgs, consider:

  • Users of xadm are authenticated and authorized to use the server (see 'admin_jamf_group' server config)
  • You don't need to distribute your signing certificates to a wide group of individual developers.
  • While you need to trust your xadm users not to upload a malicious pkg, this would be true even if you deployed the certs to them, so keeping the certs on the server is more secure.

If this feature is enabled folks using xadm do not need to sign their .pkgs. However...

Don't forget to Sign Your Apps!

While Xolo will sign your .pkg files, it cannot do anything with the contents of those packages.

If you are installing any apps or other executables that require signing, you probably need to sign them with an appropriate Application signing identity. Xolo will also not sign any embedded component packages. While signing component packages may not be totally necessary, it helps ensure secure package deployment.

[ ToC ]

Pilot, Release, and Excluded Groups

Pilot Groups

Versions can be configured with one or more 'pilot-groups', Jamf computer groups that will automatically have the version installed as soon as you've created it, before you release it. You can use different groups for different versions.

By default, a new version will inherit the pilot groups from the previous verson.

This can be useful if you have multiple simultaneous branches of development for your software, and want to test them on different groups of Macs at the same time.

When a new version is added, and its status is pilot, the scope-target of the initial auto-install policy is set to the pilot group(s). For those with the title already installed, the scope targets of the patch policy is also set to the pilot group(s). Macs in these groups should get the new version at the next checkin.

The pilot groups only define which Macs will get the new version automatically and immediately. It can be manually installed for piloting on any Mac that isn't excluded, using either xadm deploy [title] [version] [computer ...] from your own Mac, or sudo xolo install [title] [version] on the desired Mac.

Release Groups

Release groups can be assigned per title.

When a version is released the scope-target of the initial auto-install policy is changed to the release group(s). Macs in these groups that do not already have the title installed should get it at the next checkin.

The release groups only affect the automatic initial installation of a title. All computers that are not excluded can have any version of any title manually installed, either via Self Service (if enabled for the title) or xadm deploy or sudo xolo install

Since this is available on all computers that are not excluded, if you need to limit where it can be installed, be sure to exclude them.

For those with the title already installed the release group doesn't matter. The scope targets of the patch policy is also set to all computers, meaning all computers with an older version installed will get the update. Macs running newer, pilot versions should be unaffected. This happens regardless of the release groups.

Excluded Groups

Excluded groups can be assigned per title.

Computers in these groups will never have any version of the title installed via the Xolo-maintained policies.

It will not be available for manual or self service installation.

In addition to the excluded groups defined per title, the Xolo server can be configured with a single group that is always excluded from everything in Xolo.

Computers that are 'frozen' for a title are also excluded from all policies related to the title (see below).

[ ToC ]

Releasing to all computers

Some titles need to be deployed to all computers (that aren't otherwise excluded).

To do so, set the --release-groups to 'all'

HOWEVER...

The server can be configured to only allow a specified group of people to do this.

If so, and you try to set a title's --release-groups to "all" you'll get an error telling you to contact those folks, and explain why you think this title should be automatically installed on every managed Mac. That team can then, if they approve, set the release-groups to 'all'

NOTE: Items in Self Service are available to all except the excluded groups, and do not require approval.

[ ToC ]

Self Service

Titles can be made to appear in Self Service using xadm, in a specific Category and with an icon.

When a title is configured to be in Self Service, only the currently-released version is availble. If no versions are released yet, it won't appear in Self Service.

It will be visible to all computers that are not excluded, so if you need to limit who can see it, be sure to exclude all who should not see it. This may mean defining a smart group with backward-ish logic: it must include all Macs that should NOT be able to install the title.

[ ToC ]

Freezing and Thawing

To 'freeze' a computer or computer group for a title, you use xadm freeze [title] and provide the names of the computers or groups.

Once frozen, whatever version they have currently installed will remain - all updates of the title will be ignored until they are 'thawed' for that title. This means if you freeze a computer that doesn't have the title installed yet, it will never get installed.

This is useful when one or more teams using your software need to be locked in to a specific version for some time, while you continue to develop, pilot, and release new versions to the rest of the organization.

[ ToC ]

MDM deployment

If the .pkg uploaded for a version is a 'distribution package' (a.k.a. 'product archive'), then xadm (on your own machine) can be used to install it on any managed Mac anywhere on the internet. See xadm help deploy. This uses Jamf Pro's ability to send the InstallEnterpriseApplication MDM command, to install the package.

Using xadm deploy is all about doing manual initial installs on machines that would not normally have a thing automatically installed. It means that instead of ssh'ing to the target computer and typing sudo xolo install [title] [version] you stay at your own machine and type xadm deploy [title] [version] [computer ...]

The MDM command to install the package will be queued up by Jamf Pro, and will happen whever the target computer comes online, anywhere in the world. This is useful when the target machine is not on the local network and you have no way to ssh into it.

Note: Any automatic installations will already happen anywhere on the internet, without the need for MDM deployment, be that initial installation via membership in pilot or release groups or updates on any machine with a title already installed

[ ToC ]

Changelog

The Xolo server maintains a change log of all changes to a title and its versions. See xadm help changelog

[ ToC ]

JSON output

When using xadm to display info, reports, or lists of any kind, use the --json global option to get formatted JSON output, rather than text for human eyes.

This can be useful when automating the use of xadm.

[ ToC ]

Xolo Server API

While xadm is the preferred way to interact with the Xolo server, all that interaction is done via an HTTPS API, by exchanging JSON data with specific endpoints on the server. Even though this has many similarities to a REST API, it wasn't developed with the standards of REST in mind, so we refrain from calling it that.

There may be times when you want to access the server using those endpoints yourself, rather than using xadm, for example, on a Continuous Integration node where you don't have ruby installed, and can't use xadm.

While doing so is not explicitly supported, the API documentation should help you do that if needed.

Since you'll be replicating some of what xadm does, feel free to look at the xolo-admin code, to see how it does its thing.

[ ToC ]

Uninstallation

Jamf Pro sorta-mostly no longers supports un-installing the pkgs it installs via a policy action, scripts are recommended.

Xolo can be made to do so using Jamf-based scripts and a custom policy-trigger. There are two ways to do this:

  • A hand-written script that will run on the client machine.

    It's up to you to do whatever is needed to remove the title. This is useful when the title has it's own uninstaller that gets installed with the title.

  • Provide the title with one or more 'uninstall-ids'.

    These are package-identifiers in the OS's package DB, as shown in the output of pkgutil --pkgs.

    Xolo will use the identifiers to create a zsh script that uses pkgutil to identify and delete every file installed by the identified packages. Folders that have any contents after deleting the installed files, are not deleted, which might leave odd droppings.

    WARNING
    This is only recommended for very simple packages. Please test very carefully before using these scripts widely. Look at the script that is generated in Jamf Pro to see what it does.

In either case. the end result of the uninstall script should be that the title's app-name and app-bundle-id are no longer on the machine, or if the title uses a version-script, it returns no installed version.

NOTE: While uninstallation is required for a title to be 'expirable', for the most part, uninstall scripts are not needed. Please be sure it is needed before adding one.

[ ToC ]

Expiration

Like its predecessor d3, Xolo can uninstall titles when they haven't been used in some period of time.

To enable expiration:

  • Add an uninstall script to the title (see above)
  • Set an expiration period (number of days of disuse) for the title with --expiration
  • Set one or more paths to executables that must be used within the expiration period, with --expire-paths

Xolo's definition of 'usage' is based on the OS's kMDItemLastUsedDate which is the last time a thing was opened via LaunchServices (double-click, the 'open' command, a URL, etc). This might be problematic for folks who never quit Apps, so beware.

[ ToC ]

Automated Cleanup

Every night, the xolo server automatically cleans up old versions like so:

  • Delete any version that was skipped
    • Skipped means: never released, but older than the current release
    • This happens the night after any new release
  • Delete any version that has been deprecated for more than some number of days
    • Deprecated means: was released, but now older than the current release
    • The exact number of days can be configured on the server, but defaults to 90
  • Nag about old pilots
    • When a version has been in pilot for more than some number of days, monthly emails will be sent to the title's contact address asking someone to release it or delete it
    • The exact number of days can be configured on the server, but defaults to 180

As you can see from What Xolo Does, for each Title and Version, there are many objects kept in Jamf Pro: policies, packages, scripts, and more.

In order to avoid bogging down the Jamf server with excess cruft, please delete any versions, or entire titles, if the are not needed anymore.

[ ToC ]

Subscribed Titles - Xolo v2

Patch Sources

Jamf's patch management system is based on "Patch Sources" - external servers that provide information about titles and their versions. Jamf Pro can be connected to any number of patch sources. Once connected, Jamf Pro can 'activate' or 'subscribe to' any of the titles offered by a patch source. Once subscribed, the title can be managed by Jamf Pro, and new versions can be deployed easily and somewhat automatically.

Patch sources do not provide the .pkg installers, just information defining a title and its versions, and notifications when new versions are available.

Jamf.com provides a built-in patch source with Jamf Pro which provides several hundred common third-party titles. Jamf.com updates those titles when new versions are available.

They also provide access to the "Title Editor" - a cloud-based 'custom' patch source where Jamf customers can define their own titles and versions.

Xolo is written on top of this Patch Management system and it uses the Title Editor as the patch source to maintain xolo-managed titles.

Xolo's 'managed' vs 'subscribed' titles

Most titles in Xolo are 'managed' - All the definitions of the title and its versions are controlled by Xolo via someone using xadm. While Xolo uses the Title Editor patch source behind the scenes, it controls everything about the title and its versions.

Xolo v2 is able to 'subscribe' to titles managed by any patch source. For example, the title '1password 8' is available in the Jamf built-in patch source. Xolo will be able to subscribe to that title, in which case the basic definition of the title and its versions will come from that source, not under Xolo's control.

When new versions of a subscribed title appear, Jamf Pro will notify the Xolo server, which will automatically create the new version in xolo. By default, the xolo server will notify the contact email that a new version is available and needs a .pkg to be uploaded.

If the title is configured with AutoPkg integration (see below), then when the xoloserver receives notification from Jamf of a new version, a .pkg will be automatically created and uploaded, and if any pilot-groups are defined for the title, they will get the new version for piloting ASAP, automatically.

Titles developed at Pixar will always be 'managed', but those published by third parties may be managed, or subscribed if they are available via a Patch Source.

IMPORTANT : If a subscribed title has an Extension Attribute (aka version-script) Someone MUST accept it in the Jamf Pro web app The server's --jamf-auto-accept-xolo-eas setting only applies to managed titles.

Enabling Subscribed Titles

Create a token

Create a token to be used by the Jamf Pro server for webhook authentication. Any sufficiently long, unique, and random value will work, for example the output of uuidgen. This value is basically a password and should be treated as such.

  • On the Xolo server machine, set the subscription_webhook_tokenconfiguration setting to use that value.

    xoloserver config --set --subscription-webhook-token 'something goes here'

    Note that you don't need to put the value directly into the configuration, you can use external tools to retrieve it from a secrets-management system, or read it from a separate file. See Sensitive Values in xoloserver config

Optionally set an alert tool for subscribed titles

If you would like alerts about subscribed titles to use a different tool than normal Xolo alerts (or different options to the same tool), set the subscription_updated_alert_tool on the server.

Create a Jamf Pro Webhook

Create a Webhook in Jamf Pro that will send notifications to the xolo server when new versions are available to known titles

  • Navigate to Setting -> Global -> Webhooks

  • Click + New in the upper right

  • Set an appropriate Display Name for the webhook, e.g. Xolo Subscription Updates

  • Make sure its enabled

  • The webhook URL will be the hostname of your xolo server followed by subscribed-title-updates. For example:

    https://my-xoloserver.mybiz.com/subscribed-title-updates

  • Set the authentication type to Header Authentication

  • The Header metadata JSON will look like this:

    { "Authorization": "Bearer token-goes-here" }

    replacing token-goes-here with the token you created above.

  • The default timeouts should be fine, but feel free to adjust them if there's a lag between your Jamf Pro and Xolo servers.

  • Set the Content Type to JSON

  • Set the Webhook Event to PatchSoftwareTitleUpdated

    Its OK if you have other webhooks configured with that event, Jamf Pro will honor all of them, and the Xolo server will ignore events for titles it doen't know about.


XoloSubscribedTitlesWebhook

Creating a Subscribed Title

Get the Patch Source and Title ID for the desired title

To create a subscribed title, you need to know the name of the Patch Source providing it to Jamf Pro, as well as the "Title ID" for the title on that source.

To see a list of titles available for subscription, use xadm list-available which will show the Display Name, Publisher, Patch Source name, and Title ID for all available titles.

NOTE: Titles that are already subscribed in Xolo, or are activated in Jamf Patch outside of Xolo, will not be listed.

Add the title to Xolo

Use xadm add-title like normal, but:

  • Provide --subscribed, --patch-source <name>, and --title-id <id>
  • Do not provide --display-name, --publisher, --app-name, --app-bundle-id, or --version-script
    • These values come from tjhe patch source
  • Provide a --description and all other values as normal.

NOTE: Subscribed titles cannot be changed into managed titles, and vice versa.

[ ToC ]

AutoPkg integration - Xolo v2

AutoPkg is a tool for automatically fetching and/or building .pkg installers for various titles, and can be used with any deployment system. It uses publicly available 'recipes' to download the latest version of some piece of software and if needed, build a .pkg installer. There are many repositories of recipes available online, covering thousands of titles.

Version 2 of Xolo is able to use AutoPkg to automatically acquire a .pkg whever a new version is created, for either a managed or a subscribed title.

This basically means that, for such a title, no one should ever have to use the --pkg-to-upload option when adding versions to managed titles, or when a subscribed title sees a new version.

Xolo's use of Autopkg is minimal. It expects AutoPkg to be installed and configured on the Xolo server machine totally separately from Xolo itself. To make a title use AutoPkg, you configure the server with the path to the autopkg executable, and the username of the local user that will execute it (autopkg cannot be run as root). Then you set the title to know the name of the autopkg recipe it will use, and the directory where it will find the new .pkg after the recipe is run.

IMPORTANT: AutoPkg recipes are always run with -k FAIL_RECIPES_WITHOUT_TRUST_INFO=yes, and will fail if you have not 'trusted' them by making an override. See the AutoPkg docs for details.

After the recipe is run, xoloserver looks in the given directory, and uses the most recent .pkg file it finds there.

Xoloserver then uses that .pkg exactly as it would a .pkg uploaded via xadm, uploading it to the distribution point(s).

Configuring Xolo to use AutoPkg

Install AutoPkg on the Xolo Server host

You can install AutoPkg as normal, using the instructions in the AutoPkg Wiki

  • If needed, create a local user account to install and run autopkg

  • Create an override for any recipes you plan to use with Xolo. You don't need to modify the override, but it must exist.

  • Run a few recipes manually to make sure things are working

    • Be sure to grant any TCC access required, so that everything works when the xoloserver runs recipes

Configure xoloserver to use AutoPkg

  • On the Xolo server machine

    • set the autopkg_executableconfiguration setting:

      xoloserver config --set --autopkg-executable '/path/to/autopkg'

    • set the autopkg_userconfiguration setting:

      xoloserver config --set --autopkg-user 'username'

    • If any recipes will use that user's login keychain (e.g. to sign things) set the autopkg_user_keychain_pwconfiguration setting:

      xoloserver config --set --autopkg-user-keychain-pw 'something goes here'

      If this is set, xoloserver will unlock the keychain before running any recipes.

      Note that you don't need to put the password directly into the configuration, you can use external tools to retrieve it from a secrets-management system, or read it from a separate file. See Sensitive Values in xoloserver config

    • If you would like xoloserver to automatically sign any un-signed .pkg files created by autopkg, set the sign_autopkg_pkgs setting:

      xoloserver config --set --sign-autopkg-pkgs

      This is similar to, but separate from the general --sign-pkgs setting, which only applies to managed titles.

      WARNING: Signing packages acquired automatically has inherent security risks - be sure you trust your autopkg recipes before enabling this!

Configure a Title to use AutoPkg

When adding or editing a title, set these values:

  • --autopkg-recipe 'RecipeName.pkg

    • Usually you'll want .pkg or .download recipes

  • --autopkg-dir /path/to/dir/with/new/pkg/

    • The absolute path to the directory that will contain the .pkg after the recipe has run.

Subscribed and AutoPkg Together or Not

Subscribed titles and AutoPkg are separate-but-related features. They will often be used together, but don't have to be:

Uploaded Pkgs AutoPkg Pkgs
Managed Titles This is the 'normal' kind of xolo title. Versions are added with xadm add-version and either then, or later with edit-version , someone must use --pkg-to-upload to provide a .pkg for the version. Versions must still be added with xadm add-version but when that happens, the package for the version will be automatically acquired by the server using AutoPkg. If there are problems with the AutoPkg process, a pkg can be manually re-uploaded with xadm edit-version <title> <version> --pkg-to-upload /path/to/local/installer.pkg
Subscribed Titles When xoloserver learns that a new version is available, it will automatically do the equivalent of xadm add-version and will send notifications and emails telling someone to acquire an appropriate .pkg and upload it with xadm edit-version <title> <version> --pkg-to-upload /path/to/local/installer.pkg When xoloserver learns that a new version is available, it will automatically do the equivalent of xadm add-version and when that happens, the package for the version will be automatically acquired by the server using AutoPkg. Notifications will be sent saying that the new version is available for pilot. (Releasing of versions is never automated, nor should you ever automate it!)

[ ToC ]

Clone this wiki locally