-
Notifications
You must be signed in to change notification settings - Fork 191
Getting Started
Nudge has two main items that must be configured for it to be useful in production. They are a LaunchAgent and a Configuration. Nudge is configured using two primary methods:
- Configuration Profile (Typically delivered via MDM)
- JSON file
We will explore a basic LaunchAgent as well as both methods of configuring nudge using the examples found in Example Assets
The first step is to install Nudge.app itself. Nudge is extremely safe to install without configuration as it doesn't do anything unless it is configured and has a LaunchAgent configured to open it on a cadence. Install the latest version from the releases page. You will want the package that has a name similar to Nudge-1.x.x.x.x.x.pkg.
Before we are ready to create a LaunchAgent, we must pick a configuration method and confirm it is working as intended.
First, grab a copy of the example configuration profile from Example Assets. It is named com.github.macadmins.Nudge.mobileconfig and can be downloaded by clicking the file name, selecting Raw in upper right corner of the code box, then right click anywhere in the page, select Save As... and save it in your favorite directory.
This configuration profile contains all of the default values for Nudge itself. Deploying it as-is would not be very useful, so we will customize the settings first.
Only settings which are different from the defaults need to be changed. For instance, if you want to change the text on the quit button, you would change the primaryQuitButtonText key. If you are happy with the default text of "Later", you do not need to set the key
First we will make the most basic config profile we can. Delete everything out of the downloaded example profile except for the following items:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>PayloadContent</key>
<array>
<dict>
<key>PayloadDescription</key>
<string>Configures all Nudge preferences</string>
<key>PayloadDisplayName</key>
<string>Nudge Preferences</string>
<key>PayloadIdentifier</key>
<string>com.github.macadmins.Nudge.preferences.example</string>
<key>PayloadOrganization</key>
<string></string>
<key>PayloadType</key>
<string>com.github.macadmins.Nudge</string>
<key>PayloadUUID</key>
<string>CA02957C-7472-446B-9F77-3E0414405556</string>
<key>PayloadVersion</key>
<integer>1</integer>
<key>osVersionRequirements</key>
<array>
<dict>
<key>requiredInstallationDate</key>
<date>2021-02-28T00:00:00Z</date>
<key>requiredMinimumOSVersion</key>
<string>11.2.1</string>
<key>targetedOSVersions</key>
<array>
<string>11.0</string>
<string>11.0.1</string>
<string>11.1</string>
<string>11.2</string>
</array>
</dict>
</array>
</dict>
</array>
<key>PayloadDescription</key>
<string>Configures Nudge application</string>
<key>PayloadDisplayName</key>
<string>Nudge</string>
<key>PayloadIdentifier</key>
<string>com.github.macadmins.Nudge.example</string>
<key>PayloadOrganization</key>
<string>Nudge</string>
<key>PayloadScope</key>
<string>System</string>
<key>PayloadType</key>
<string>Configuration</string>
<key>PayloadUUID</key>
<string>2F54F734-132D-4539-B583-F1DCF23DB5EB</string>
<key>PayloadVersion</key>
<integer>1</integer>
</dict>
</plist>Within this profile, we will focus on the osVersionRequirements key:
<key>osVersionRequirements</key>
<array>
<dict>
<key>requiredInstallationDate</key>
<date>2021-02-28T00:00:00Z</date>
<key>requiredMinimumOSVersion</key>
<string>11.2.1</string>
<key>targetedOSVersions</key>
<array>
<string>11.0</string>
<string>11.0.1</string>
<string>11.1</string>
<string>11.2</string>
</array>
</dict>
</array>The primary keys which are required for Nudge to do its thing are as follows:
requiredInstallationDate is the required installation date for Nudge to enforce the required operating system version.
requiredMinimumOSVersion is the required minimum operating system version. That is, Nudge will ask people to update until they are at this version or later. If the current version of macOS is higher than or equal to the requiredMinimumOSVersion, Nudge will not open.
targetedOSVersions is a list of macOS versions which determines which versions of macOS that Nudge will launch on. If the current version of macOS on the machine launching Nudge is not in this list, Nudge will not open.
To ensure we always get a prompt while testing, we need to make sure the version of macOS that we are running Nudge on is both in the targetedOSVersions list as well as below the value in requiredMinimumOSVersion.
For example, if you are currently on macOS 11.3.0, the above config means you would never see Nudge launch as you are already up to date.
Tweak the osVersionRequirements values so it looks like the values below. If this is being read in the distant future, you will need to append the targetedOSVersions to ensure your current macOS version is in scope and change the requiredInstallationDate to something reasonable. Note: This is ONLY for testing purposes, never deploy it this way in production.
<key>osVersionRequirements</key>
<array>
<dict>
<key>requiredInstallationDate</key>
<date>2021-04-01T00:00:00Z</date>
<key>requiredMinimumOSVersion</key>
<string>11.99.1</string>
<key>targetedOSVersions</key>
<array>
<string>11.0</string>
<string>11.0.1</string>
<string>11.1</string>
<string>11.2</string>
<string>11.2.1</string>
<string>11.2.2</string>
<string>11.2.3</string>
<string>11.3</string>
</array>
</dict>
</array>Save the profile changes, double click it, go to System Preferences => Profiles and click install at the top. Once the profile is installed, open Nudge.app (found in /Applications/Utilities/Nudge.app)
If everything went well, you should be able to open Nudge.app and it should ask you to update macOS to the required version. If this did not happen, now is a good time to look at the documentation for Logging. For general logging around nudge, the go-to is the following log command:
log stream --predicate 'subsystem == "com.github.macadmins.Nudge"' --style syslog --color noneNow that we know the config is triggering nudge, lets change the configuration to something more suitable for production use:
<key>osVersionRequirements</key>
<array>
<dict>
<key>requiredInstallationDate</key>
<date>2021-04-01T00:00:00Z</date>
<key>requiredMinimumOSVersion</key>
<string>11.2.3</string>
<key>targetedOSVersions</key>
<array>
<string>11.0</string>
<string>11.0.1</string>
<string>11.1</string>
<string>11.2</string>
<string>11.2.1</string>
<string>11.2.2</string>
</array>
</dict>
</array>After changing the config as shown above, save it, reinstall it and run Nudge. If you are already on 11.2.3+, Nudge shouldn't open at all. If you are on an older version of macOS, you should get the Nudge prompt to update. For versions that should be listed in targetedOSVersions, the wikipedia page for macOS 11 is a good place to start.
It is worth noting that if you are requiring version 11.2.3, make sure to only target versions prior to that in targetedOSVersions.
To do a simple test with the LaunchAgent, continue on to the LaunchAgent section of this guide.
First, grab a copy of the example JSON configuration file from Example Assets. It is named com.github.macadmins.Nudge.json and can be downloaded by clicking the file name, selecting Raw in upper right corner of the code box, then right click anywhere in the page, select Save As... and save it in your favorite directory.
This JSON configuration contains all of the default values for Nudge itself. Deploying it as-is would not be very useful, so we will customize the settings first.
Only settings which are different from the defaults need to be changed. For instance, if you want to change the text on the quit button, you would change the primaryQuitButtonText key. If you are happy with the default text of "Later", you do not need to set the key
First we will make the most basic JSON config we can. Delete everything out of the downloaded example JSON except for the following items:
{
"osVersionRequirements": [
{
"requiredInstallationDate": "2021-02-28T00:00:00Z",
"requiredMinimumOSVersion": "11.2.1",
"targetedOSVersions": [
"11.0",
"11.0.1",
"11.1",
"11.2"
]
}
]
}The primary keys which are required for Nudge to do its thing are as follows:
requiredInstallationDate is the required installation date for Nudge to enforce the required operating system version.
requiredMinimumOSVersion is the required minimum operating system version. That is, Nudge will ask people to update until they are at this version or later. If the current version of macOS is higher than or equal to the requiredMinimumOSVersion, Nudge will not open.
targetedOSVersions is a list of macOS versions which determines which versions of macOS that Nudge will launch on. If the current version of macOS on the machine launching Nudge is not in this list, Nudge will not open.
To ensure we always get a prompt while testing, we need to make sure the version of macOS that we are running Nudge on is both in the targetedOSVersions list as well as below the value in requiredMinimumOSVersion.
For example, if you are currently on macOS 11.3.0, the above config means you would never see Nudge launch as you are already up to date.
Tweak the osVersionRequirements values so it looks like the values below. If this is being read in the distant future, you will need to append the targetedOSVersions to ensure your current macOS version is in scope and change the requiredInstallationDate to something reasonable. Note: This is ONLY for testing purposes, never deploy it this way in production.
{
"osVersionRequirements": [
{
"requiredInstallationDate": "2021-04-01T00:00:00Z",
"requiredMinimumOSVersion": "11.99.1",
"targetedOSVersions": [
"11.0",
"11.0.1",
"11.1",
"11.2",
"11.2.1",
"11.2.2",
"11.2.3",
"11.3"
]
}
]
}Save the JSON changes, and copy it into the default config location using the following command:
sudo cp ./com.github.macadmins.Nudge.json /Library/Preferences/If everything went well, you should be able to open Nudge.app and it should ask you to update macOS to the required version. If this did not happen, now is a good time to look at the documentation for Logging. For general logging around nudge, the go-to is the following log command:
log stream --predicate 'subsystem == "com.github.macadmins.Nudge"' --style syslog --color noneNow that we know the config is triggering nudge, lets change the configuration to something more suitable for production use:
{
"osVersionRequirements": [
{
"requiredInstallationDate": "2021-04-01T00:00:00Z",
"requiredMinimumOSVersion": "11.2.3",
"targetedOSVersions": [
"11.0",
"11.0.1",
"11.1",
"11.2",
"11.2.1",
"11.2.2",
]
}
]
}After changing the config as shown above, save it, copy it into place and run Nudge. If you are already on 11.2.3+, Nudge shouldn't open at all. If you are on an older version of macOS, you should get the Nudge prompt to update. For versions that should be listed in targetedOSVersions, the wikipedia page for macOS 11 is a good place to start.
It is worth noting that if you are requiring version 11.2.3, make sure to only target versions prior to that in targetedOSVersions.
To do a simple test with the LaunchAgent, continue on to the LaunchAgent section of this guide.
For the launchagent, there is a default option available that will work for most everyone unless you use a non-standard location for the json configuration file.
An Apple package for this LaunchAgent can be found on the releases page.
To use the default LaunchAgent, install the latest version of the Nudge_LaunchAgent-x.x.x.pkg package. It will place the LaunchAgent and load it in the current active console user's session.
Congratulations, you now have a working Nudge config!