mirror of
https://github.com/jamf/Setup-Manager.git
synced 2026-02-03 14:13:24 +00:00
Compare commits
19 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
23484fe7ae | ||
|
|
dc5f251ac3 | ||
|
|
61d6a307e9 | ||
|
|
8113c0baf4 | ||
|
|
e96ac17616 | ||
|
|
f50cf5146b | ||
|
|
09016086f7 | ||
|
|
741bcb47e7 | ||
|
|
cc3e7cbfc6 | ||
|
|
c26f42bda7 | ||
|
|
7720d56ea7 | ||
|
|
fb4d6c84e0 | ||
|
|
d647234e37 | ||
|
|
dd25148186 | ||
|
|
552f8e7fc1 | ||
|
|
290c68cfe2 | ||
|
|
44f4c4513c | ||
|
|
29489d9b6f | ||
|
|
9368026e74 |
366
ChangeLog.md
366
ChangeLog.md
@@ -1,5 +1,371 @@
|
||||
# Setup Manager - Change Log
|
||||
|
||||
## 1.4
|
||||
|
||||
(2025-12-03)
|
||||
|
||||
While making sure that Setup Manager looks nice with macOS Tahoe and Liquid Glass, we have added a few more features to improve customization.
|
||||
|
||||
### New Features
|
||||
- User Interface
|
||||
- macOS Tahoe/Liquid Glass adaptions
|
||||
- new `banner` key allows you to provide a banner image that cover the top part of the Setup Manager window ([details](ConfigurationProfile.md#banner))
|
||||
- `title` and `icon` keys are now optional, when a `banner` key is set
|
||||
- action tiles can have a background color set with the top-level or per-action 'tileColor'key
|
||||
- `banner` and `background` can use hex or system colors
|
||||
- where colors are defined, you can use system color names. See ['Defining Colors'](ConfigurationProfile.md#defining-colors) for details
|
||||
- new profile keys:
|
||||
- `networkQualityCheck` suppresses network bandwidth calculation when set to `false` (#135)
|
||||
- `finishedMessage` for a customized message when Setup Manager workflow is complete (#128)
|
||||
- logging:
|
||||
- new tab for configuration profiles in the log
|
||||
- detection of configuration profile installation and removal
|
||||
- image/icon load errors are now logged
|
||||
- logs a warning when Setup Manager detects it is launched for a second time
|
||||
- switched launch tracking to a new service (see [Launch Tracking](Docs/LaunchTracking.md) for details)
|
||||
|
||||
### Fixes and Improvements
|
||||
|
||||
- disabled check for Jamf.app as it could fail in some challenging network configs
|
||||
- enrollmentUserID added to webhook data (#140)
|
||||
- localization fixes (#149)
|
||||
- elapsed time in Mac Info window stops counting when workflow is finished
|
||||
- link to computer in Slack and Teams messages should work with Jamf School
|
||||
- setting computer name with user entry or `computerNameTemplate` works with Jamf School
|
||||
- updated uninstall.sh script (#156)
|
||||
- (beta2) Localization:
|
||||
- added UK English (en-GB) localization (thanks to @philipross)
|
||||
- various localization fixes (#171)
|
||||
- (beta2) fixed Network Info font color (#166)
|
||||
- (beta2) `waitForUserEntry` action correctly runs a recon/Update Inventory (#168)
|
||||
- (beta2) `accentColor` affects all items and controls (#170)
|
||||
- (beta2) UI adjustments (#169)
|
||||
|
||||
|
||||
### Changes, deprecations and removals
|
||||
- (1.4) `userID` top-level key name changed to `enrollmentUserID`
|
||||
- (1.4) `jssID` key has been renamed to `computerID`
|
||||
- (1.3) the minimum macOS requirement for Setup Manager is now macOS 13.5
|
||||
- (1.2) `showBothButtons` option removed and non-functional, there will always be just one final action button displayed
|
||||
- (1.1)the method for providing localized texts in the configuration profile changed in version 1.1. The previous method (by appending the two letter language code to the key) is considered deprecated. It will continue to work for the time being but will be removed in a future release. It is _strongly_ recommended to change to the [new dictionary-based solution](ConfigurationProfile.md#localization)
|
||||
|
||||
### Notes
|
||||
|
||||
There are quite a few new options in Setup Manager 1.4 beta to configure and customize the new UI. There is a new option for a color or image banner across the top of the Setup Manager window. Action tiles can now be colored automatically or with specific colors. Colors can now be set anywhere that image sources are used and you get a list of named system colors.
|
||||
|
||||
While the [description of all the keys in the repo](ConfigurationProfile.md) has been updated, many of the keys, old and new, now work together for a variety of useful combinations.
|
||||
|
||||
#### Updating the profile to use 1.4 (beta) features
|
||||
|
||||
The good news first: we designed the update so that you can keep using the same profile from earlier versions and the Setup Manager window will look mostly the same on macOS Sequoia and earlier, and have the new “Liquid Glass” look and feel on macOS Tahoe.
|
||||
|
||||
To use the new UI options, set the new keys.
|
||||
|
||||
#### Banner
|
||||
|
||||
Setup Manager 1.4 introduces the option to show a color or image banner in the top of the Setup Manager window. This is controlled by the top-level [`banner` key](ConfigurationProfile.md#banner). The `banner` value is an [image source](ConfigurationProfile.md#icon-sources), so it can be a reference to local image file, an image file hosted on a web server, or (also new in 1.4) a [color designation](ConfigurationProfile.md#defining-colors).
|
||||
|
||||
Colors can be set with hex codes, e.g. `#f00` or `#f900a2` or with (new in 1.4) system color names, e.g. `##gray`, `##red`, etc.
|
||||
|
||||
The size of the banner area is 800x233 pixels (1600x466 @2x) on Sequoia and earlier and 800x247 (1600x494 @2x) on Tahoe (the liquid glass tool bar is taller). The image will be displayed with bottom-center alignment and _not_ scaled, so you can add a few extra pixels at the top and the same image should work for all macOS versions.
|
||||
|
||||
The behavior of the `icon` and `title` keys changes depending on whether the `banner` has a value.
|
||||
|
||||
When _no_ `banner` value is set, Setup Manager will show its app icon when an `icon` key is missing or empty. It will also show ‘Welcome’ or the localized equivalent when the `title` key is missing or empty.
|
||||
|
||||
When the `banner` _is_ set, an empty or missing `title` or `icon` will simply not be shown. This lets you use the banner image for a completely customized experience.
|
||||
|
||||
Note that the `banner` value can be localized.
|
||||
|
||||
#### Action Tile Colors
|
||||
|
||||
Setup Manager 1.4 allows you to set a color for the action tiles. Use the [top-level `tileColor` key](ConfigurationProfile.md#tilecolor) to set the color for all action tiles. You can also set the tile color for an individual action with [a `tileColor` key in the action](ConfigurationProfile.md#tilecolor-1).
|
||||
|
||||
When no `tileColor` is set, the default behavior is to use the window background color (gray on Sequoia and earlier, white on Tahoe, or the dark mode equivalent).
|
||||
|
||||
You can set the `tileColor` value (top-level and action level) to [a hex color or system color name](ConfigurationProfile.md#defining-colors). There are a few special color names:
|
||||
|
||||
- `##automatic`: calculates each tile's color from the average color of each action’s icon, icons defined with `symbol:…` will use the default color
|
||||
- `##background`: system window background (gray on Sequoia and earlier, white on Tahoe)
|
||||
- `##clear`: transparent or no background, works best when `hideActionLabels` is set to false
|
||||
|
||||
See [`tileColor`](ConfigurationProfile.md#tilecolor-1) and [‘Defining Colors’](ConfigurationProfile.md#defining-colors) in the documentation for details.
|
||||
|
||||
#### Profile Installation and Removal Logging
|
||||
|
||||
A new tab has been added to logging window which logs the installation and removal of configuration profiles. These events will also be logged to the main Setup Manager log, which allows you to see them in context of the entire workflow.
|
||||
|
||||
This can be especially useful to determine whether a particular profile disrupts the network and possibly the download of an important component. In the unified system log, these entries will have the `profile` category.
|
||||
|
||||
|
||||
## 1.4beta2
|
||||
|
||||
(2025-11-24)
|
||||
|
||||
Same as [the previous beta](https://github.com/jamf/Setup-Manager/releases/tag/v1.4beta) with these additional changes:
|
||||
|
||||
- Localization:
|
||||
- added UK English (en-GB) localization
|
||||
- various localization fixes (#171)
|
||||
- fixed Network Info font color (#166)
|
||||
- `waitForUserEntry` action correctly runs a recon/Update Inventory (#168)
|
||||
- `accentColor` affects all items and controls (#170)
|
||||
- UI adjustments (#169)
|
||||
|
||||
## v1.4beta
|
||||
(2025-10-28)
|
||||
|
||||
While making sure that Setup Manager looks nice with macOS Tahoe and Liquid Glass, we have added a few more features to improve customization.
|
||||
|
||||
### New Features
|
||||
- User Interface
|
||||
- macOS Tahoe/Liquid Glass adaptions
|
||||
- new `banner` key allows you to provide a banner image that cover the top part of the Setup Manager window ([details](ConfigurationProfile.md#banner))
|
||||
- `title` and `icon` keys are now optional, when a `banner` key is set
|
||||
- action tiles can have a background color set with the top-level or per-action 'tileColor'key
|
||||
- `banner` and `background` can use hex or system colors
|
||||
- where colors are defined, you can use system color names. See ['Defining Colors'](ConfigurationProfile.md#defining-colors) for details.
|
||||
- new profile keys:
|
||||
- `networkQualityCheck` suppresses network bandwidth calculation when set to `false` (#135)
|
||||
- `finishedMessage` for a customized message when Setup Manager workflow is complete (#128)
|
||||
- logging:
|
||||
- new tab for configuration profiles in the log
|
||||
- detection of configuration profile installation and removal
|
||||
- image/icon load errors are now logged
|
||||
- logs a warning when Setup Manager detects it is launched for a second time
|
||||
- switched launch tracking to a new service (see [Launch Tracking](Docs/LaunchTracking.md) for details)
|
||||
|
||||
### Fixes and Improvements
|
||||
|
||||
- disabled check for Jamf.app as it could fail in some challenging network configs
|
||||
- enrollmentUserID added to webhook data (#140)
|
||||
- localization fixes (#149)
|
||||
- elapsed time in Mac Info window stops counting when workflow is finished
|
||||
- link to computer in Slack and Teams messages should work with Jamf School
|
||||
- setting computer name with user entry or `computerNameTemplate` works with Jamf School
|
||||
- updated uninstall.sh script (#156)
|
||||
|
||||
### Changes, deprecations and removals
|
||||
- (1.4) `userID` top-level key name changed to `enrollmentUserID`
|
||||
- (1.4) `jssID` key has been renamed to `computerID`
|
||||
- (1.3) the minimum macOS requirement for Setup Manager is now macOS 13.5
|
||||
- Log window now uses `Window`
|
||||
- (1.2) `showBothButtons` option removed and non-functional, there will always be just one final action button displayed
|
||||
- (1.1)the method for providing localized texts in the configuration profile changed in version 1.1. The previous method (by appending the two letter language code to the key) is considered deprecated. It will continue to work for the time being but will be removed in a future release. It is _strongly_ recommended to change to the [new dictionary-based solution](ConfigurationProfile.md#localization)
|
||||
|
||||
### Notes
|
||||
|
||||
There are quite a few new options in Setup Manager 1.4 beta to configure and customize the new UI. There is a new option for a color or image banner across the top of the Setup Manager window. Action tiles can now be colored automatically or with specific colors. Colors can now be set anywhere that image sources are used and you get a list of named system colors.
|
||||
|
||||
While the [description of all the keys in the repo](ConfigurationProfile.md) has been updated, many of the keys, old and new, now work together for a variety of useful combinations.
|
||||
|
||||
#### Updating the profile to use 1.4 (beta) features
|
||||
|
||||
The good news first: we designed the update so that you can keep using the same profile from earlier versions and the Setup Manager window will look mostly the same on macOS Sequoia and earlier, and have the new “Liquid Glass” look and feel on macOS Tahoe.
|
||||
|
||||
To use the new UI options, set the new keys.
|
||||
|
||||
#### Banner
|
||||
|
||||
Setup Manager 1.4 introduces the option to show a color or image banner in the top of the Setup Manager window. This is controlled by the top-level [`banner` key](ConfigurationProfile.md#banner). The `banner` value is an [image source](ConfigurationProfile.md#icon-sources), so it can be a reference to local image file, an image file hosted on a web server, or (also new in 1.4) a [color designation](ConfigurationProfile.md#defining-colors).
|
||||
|
||||
Colors can be set with hex codes, e.g. `#f00` or `#f900a2` or with (new in 1.4) system color names, e.g. `##gray`, `##red`, etc.
|
||||
|
||||
The size of the banner area is 800x233 pixels (1600x466 @2x) on Sequoia and earlier and 800x247 (1600x494 @2x) on Tahoe (the liquid glass tool bar is taller). The image will be displayed with bottom-center alignment and _not_ scaled, so you can add a few extra pixels at the top and the same image should work for all macOS versions.
|
||||
|
||||
The behavior of the `icon` and `title` keys changes depending on whether the `banner` has a value.
|
||||
|
||||
When _no_ `banner` value is set, Setup Manager will show its app icon when an `icon` key is missing or empty. It will also show ‘Welcome’ or the localized equivalent when the `title` key is missing or empty.
|
||||
|
||||
When the `banner` _is_ set, an empty or missing `title` or `icon` will simply not be shown. This lets you use the banner image for a completely customized experience.
|
||||
|
||||
Note that the `banner` value can be localized.
|
||||
|
||||
#### Action Tile Colors
|
||||
|
||||
Setup Manager 1.4 allows you to set a color for the action tiles. Use the [top-level `tileColor` key](ConfigurationProfile.md#tilecolor) to set the color for all action tiles. You can also set the tile color for an individual action with [a `tileColor` key in the action](ConfigurationProfile.md#tilecolor-1).
|
||||
|
||||
When no `tileColor` is set, the default behavior is to use the window background color (gray on Sequoia and earlier, white on Tahoe, or the dark mode equivalent).
|
||||
|
||||
You can set the `tileColor` value (top-level and action level) to [a hex color or system color name](ConfigurationProfile.md#defining-colors). There are a few special color names:
|
||||
|
||||
- `##automatic`: calculates each tile's color from the average color of each action’s icon, icons defined with `symbol:…` will use the default color
|
||||
- `##background`: system window background (gray on Sequoia and earlier, white on Tahoe)
|
||||
- `##clear`: transparent or no background, works best when `hideActionLabels` is set to false
|
||||
|
||||
See [`tileColor`](ConfigurationProfile.md#tilecolor-1) and [‘Defining Colors’](ConfigurationProfile.md#defining-colors) in the documentation for details.
|
||||
|
||||
#### Profile Installation and Removal Logging
|
||||
|
||||
A new tab has been added to logging window which logs the installation and removal of configuration profiles. These events will also be logged to the main Setup Manager log, which allows you to see them in context of the entire workflow.
|
||||
|
||||
This can be especially useful to determine whether a particular profile disrupts the network and possibly the download of an important component. In the unified system log, these entries will have the `profile` category.
|
||||
|
||||
|
||||
|
||||
## 1.3.1
|
||||
(2025-07-17)
|
||||
|
||||
- updates to Polish localization
|
||||
- improvements to launch process at login window
|
||||
- logs macOS version at launch
|
||||
- email addresses and urls in markdown text are not active links any more
|
||||
- documentation updates and clarifications
|
||||
|
||||
## 1.3
|
||||
(2025-07-08)
|
||||
|
||||
Notes added since 1.3beta are marked with '(release)'
|
||||
|
||||
### New Features
|
||||
- Logging
|
||||
- log output format has been cleaned up
|
||||
- Install log and Jamf Pro log (when available) can now be viewed in the Log window (#78, #130)
|
||||
- now also logs to macOS unified logging
|
||||
- new top-level default key to control action output logging
|
||||
- Network Monitoring
|
||||
- changes to network interfaces are now logged, see the Notes section for details (#15)
|
||||
- network status can be shown in the top-right corner of the Setup Manager window
|
||||
- new flag file `/private/var/db/.JamfSetupStarted`, which is created when Setup Manager starts. You can use this to scope Mac App Store apps and Jamf App Installers, which prevents these apps from installing early in the enrollment, slowing down the Jamf Pro configuration
|
||||
- added [a specific webhook to send a message to Slack](Docs/Webhooks.md#slack) (#104)
|
||||
- two new defaults keys `finishedScript` and `finishedTrigger` allow to run custom behavior when Setup Manager has finished
|
||||
- new option `none` for `finalAction` (#115)
|
||||
- (release) Polish localization (Thanks to @bsojka)
|
||||
|
||||
### Fixes and Improvements
|
||||
- Jamf Pro: improved monitoring for Jamf Pro to complete its setup after enrollment
|
||||
- webhook log entries correctly show status
|
||||
- added `-skipAppUpdates` option to list of options for Jamf Pro policy actions, this should avoid some false "error 57" reports
|
||||
- Jamf Pro policy will trigger 'Recurring Check-in' policies on empty string value
|
||||
- (release) added name for macOS Tahoe 26
|
||||
- (release) minor localization and UI fixes
|
||||
- (release) disabled some undesirable keyboard shortcuts (#125)
|
||||
- (release) arguments in `installomator` actions are now processed correctly
|
||||
- (release) output to log is flushed immediately to avoid truncation on restart/shutdown (#129)
|
||||
- (release) MDM Server address shown in extended "About this Mac" (#127)
|
||||
|
||||
### Deprecations and Removals
|
||||
- (1.3) the minimum macOS requirement for Setup Manager is now macOS 13.5
|
||||
- (1.2) `showBothButtons` option removed and non-functional, there will always be just one final action button displayed
|
||||
- the method for providing localized texts in the configuration profile changed in version 1.1. The previous method (by appending the two letter language code to the key) is considered deprecated. It will continue to work for the time being but will be removed in a future release. It is _strongly_ recommended to change to the [new dictionary-based solution](ConfigurationProfile.md#localization)
|
||||
|
||||
### Notes
|
||||
|
||||
#### Logging
|
||||
|
||||
The format of the Setup Manager log file (in `/Library/Logs/Setup Manager.log`) has changed. The new format should be easier to read and parse with other tools. There are four columns:
|
||||
|
||||
- timestamp (in ISO8601)
|
||||
- log level (default, error or fault)
|
||||
- category (general, install, network, jamfpro)
|
||||
- message
|
||||
|
||||
Setup Manager 1.3 also logs to the macOS unified system log. The subsystem is `com.jamf.setupmanager`. You can use the `log` command line tool to read the log.
|
||||
|
||||
For example:
|
||||
|
||||
```
|
||||
sudo log show --last 30m --predicate 'subsystem="com.jamf.setupmanager"'
|
||||
```
|
||||
|
||||
To clean up the log a little, Setup Manager 1.3 will only write the output of actions to the Setup Manager log file when an error occurred. You can control this behavior with a new top-level preference key `actionOutputLogging`.
|
||||
|
||||
#### Installation and Jamf Pro logs and summaries
|
||||
|
||||
The Log window (open with command-L) gained a new "Install" tab, which shows the system's installation log file (`/var/log/install.log`). When enrolling with Jamf Pro, there is another new "Jamf" tab, which shows the Jamf log (`/var/log/jamf.log`). By default, the Log window will be summarized to events relevant to the enrollment workflow. You can see the full log content by unchecking the 'Summarize' option.
|
||||
|
||||
Note that both logs will show events that were not initiated by Setup Manager. Nevertheless, these events may be relevant to your enrollment workflow.
|
||||
|
||||
These summarized events will also appear in the Setup Manager log tab and file, as well as the universal log entries. Having these events in context at the time they occur in the Setup Manager log is very helpful when trouble-shooting enrollment workflows.
|
||||
|
||||
#### Network change logging
|
||||
|
||||
Setup Manager 1.3 adds logging for changes to network interfaces. It is possible that there will multiple entries in the log with regards to the same network change. Most changes logged will be neutral and should not affect your deployment negatively.
|
||||
|
||||
However, it is possible that changes to the network configuration of a device can influence the deployment workflow. For example, when a configuration profile with the access information for a secure corporate Wifi is installed on the device, then the download access to required resources might change. Another example are security tools that might lead to restricted access for downloads (Installomator uses `curl` to download data, which might trigger security tools.)
|
||||
|
||||
Checking the log for network changes or outages during enrollment can be useful for troubleshooting.
|
||||
|
||||
#### Network Status icon/menu
|
||||
|
||||
Network status can also show with a new icon in the top-right corner of the Setup Manager window.
|
||||
|
||||
Note that Network Relay will only protect traffic to certain configured servers and services, not all traffic.
|
||||
|
||||
By default, the network icon will _not_ be shown. You can activate it manually with the command-N keystroke.
|
||||
|
||||
When you click on the Network status icon, a popup will show:
|
||||
- the current active network interface
|
||||
- IPv4 and IPv6 addresses
|
||||
- download and upload bandwidth (will take a while to appear)
|
||||
- Network Relay hosts (when network relay profile is present)
|
||||
- list of additional custom hosts, configured in the profile
|
||||
|
||||
Note that the connectivity check is quite basic and might not catch all functionality that is required for a service to work. It should provide an indication whether a service is reachable, but deeper trouble-shooting and monitoring might be required for reliable diagnostics.
|
||||
|
||||
Seen["Network Connectivity"](Docs/Network.md) for more detail.
|
||||
|
||||
#### Finished Script and Trigger
|
||||
|
||||
Setup Manager now includes functionality to launch a script or Jamf Pro custom policy trigger in a separate process when the main Setup Manager process is finished. This is useful for installations that might unexpectedly restart the computer or the context that Setup Manager is running in (most commonly, Setup Manager is running at login window, which the Jamf Connect installer will kill).
|
||||
|
||||
There are two keys relevant for this: `finishedScript` and `finishedTrigger`.
|
||||
|
||||
See ["Running Scripts and Policies when Setup Manager finishes"](Docs/Extras.md#running-scripts-and-policies-when-setup-manager-finishes) for detail.
|
||||
|
||||
## v1.3beta
|
||||
(2025-05-27)
|
||||
|
||||
### New Features
|
||||
- Logging
|
||||
- log output format has been cleaned up
|
||||
- Install log and Jamf Pro log (when available) can now be viewed in the Log window (#78)
|
||||
- now also logs to macOS unified logging
|
||||
- new top-level default key to control action output logging
|
||||
- Network Monitoring
|
||||
- changes to network interfaces are now logged, see the Notes section for details (#15)
|
||||
- network status can be shown in the top-right corner of the Setup Manager window
|
||||
- new flag file `/private/var/db/.JamfSetupStarted`, which is created when Setup Manager starts
|
||||
- added [a specific webhook to send a message to Slack](Docs/WebHooks.md#Slack) (#104)
|
||||
- two new defaults keys `finishedScript` and `finishedTrigger` allow to run custom behavior when Setup Manager has finished
|
||||
- new option `none` for `finalAction` (#115)
|
||||
|
||||
### Fixes and Improvements
|
||||
- Jamf Pro: improved monitoring for Jamf Pro to complete its setup after enrollment
|
||||
- webhook log entries correctly show status
|
||||
- added `-skipAppUpdates` option to list of options for Jamf Pro policy actions
|
||||
- Jamf Pro policy will trigger 'Recurring Check-in' policies on empty string value
|
||||
|
||||
### Deprecations and Removals
|
||||
- (1.3) the minimum macOS requirement for Setup Manager is now macOS 13.5
|
||||
- (1.2) `showBothButtons` option removed and non-functional, there will always be just one final action button displayed
|
||||
- the method for providing localized texts in the configuration profile changed in version 1.1. The previous method (by appending the two letter language code to the key) is considered deprecated. It will continue to work for the time being but will be removed in a future release. It is _strongly_ recommended to change to the [new dictionary-based solution](ConfigurationProfile.md#localization)
|
||||
|
||||
## v1.2.2
|
||||
(2025-04-17)
|
||||
- signed a helper script that could lead to unexpected background item prompts
|
||||
- disabled command-W keystroke
|
||||
- fixed a stall in `waitForUserEntry` with Jamf School
|
||||
- fixed link to computer record in Teams message (#110)
|
||||
- minor documentation fixes
|
||||
|
||||
## v1.2.1
|
||||
(2025-04-02)
|
||||
|
||||
- updated included Installomator script to [v10.8](https://github.com/Installomator/Installomator/releases/tag/v10.8)
|
||||
- now tries for 15 seconds to reload local `background` image file (#105), this should help in situations where the image file is installed after Setup Manager
|
||||
- improved monitoring of Jamf Pro enrollment process and completion during the "Getting Ready" phase
|
||||
- minor documentation fixes (#106)
|
||||
|
||||
|
||||
## v1.2.2
|
||||
(2025-04-17)
|
||||
- signed a helper script that could lead to unexpected background item prompts
|
||||
- disabled command-W keystroke
|
||||
- fixed a stall in `waitForUserEntry` with Jamf School
|
||||
- fixed link to computer record in Teams message (#110)
|
||||
- minor documentation fixes
|
||||
|
||||
## v1.2.1
|
||||
(2025-04-02)
|
||||
|
||||
|
||||
@@ -5,6 +5,7 @@ The project some sample files to get you started:
|
||||
- [sample plist](Examples/sample-waitForUserEntry.plist) for Jamf Pro with [two phase workflow](Docs/JamfPro-TwoPhase.md)
|
||||
- [configuration profile](Examples/sample-jamfschool.mobileconfig) for Jamf School
|
||||
|
||||
**Important:** all keys and values are **case-senstive**.
|
||||
|
||||
## Top-level keys
|
||||
|
||||
@@ -35,12 +36,16 @@ Example:
|
||||
<string>Welcome to your new Mac!</string>
|
||||
```
|
||||
|
||||
When `title` is empty or unset, the default message `Welcome to Setup Manager` will be shown, unless the `banner` set, when no title will be shown instead. This allows for a custom branded title and icon in the banner image.
|
||||
|
||||
#### `icon`
|
||||
|
||||
(String, default: `name:AppIcon`, localized, dark mode)
|
||||
|
||||
The icon shown at the top center of the window. There are many options to define icons, described in the [Icon Sources](#icon-sources) section later. Images will be scaled to fit a size of 700x128 pixels (or 1400x256 @2x).
|
||||
|
||||
When `icon` is empty or unset, Setup Manager will show the Setup Manager app icon, unless the `banner` is set, when no icon will be shown instead. This allows for a custom branded icon and title in the banner image.
|
||||
|
||||
#### `message`
|
||||
|
||||
(String, default: `Setup Manager is configuring your Mac…`, localized, substitutions, markdown)
|
||||
@@ -74,6 +79,27 @@ Example:
|
||||
|
||||
`Please be patient.` will be bold. More detail on [Markdown here](#markdown).
|
||||
|
||||
During the "Getting Ready" phase up to three lines of text will be shown. When the action icon progress list is shown, text will be truncated to a single line.
|
||||
|
||||
Use actual line breaks in the XML for line breaks in this text. (`\n` escape sequence will _not_ work in XML)
|
||||
|
||||
Example:
|
||||
|
||||
```xml
|
||||
<key>message</key>
|
||||
<string>Please be patient…
|
||||
|
||||
This line of text will be truncated when the action icon list is shown.</string>
|
||||
```
|
||||
|
||||
#### `banner`
|
||||
|
||||
(String, optional, localized, dark mode, v1.4)
|
||||
|
||||
When this key is set, Setup Manager treats it as an image/[icon source](#icon-sources) and displays it as a banner image in the top area of the Setup Manager window, behind the `icon` and `title`. The banner area size is 800x233 pixels (1600x466 @2x) on Sequoia and earlier and 800x247 (1600x494 @2x) on Tahoe (the liquid glass toolbar on Tahoe is taller). The banner image will _not_ be scaled down to fit. The image will be displayed with bottom-center alignment, so you can add a extra pixels at the top and the same image should work for all macOS versions.
|
||||
|
||||
When the `banner` is set, and the `title` or `icon` are empty or unset, _neither_ title message _nor_ icon will be shown. This allows for customized branding of the title area with just the banner image. Note that you can localize banner image sources.
|
||||
|
||||
#### `background`
|
||||
|
||||
(String, optional, localized, dark mode)
|
||||
@@ -84,11 +110,9 @@ When this key is set, Setup Manager treats it as an image/[icon source](#icon-so
|
||||
|
||||
(String, optional, default: `enrollment`)
|
||||
|
||||
**Beta:** We believe the run at login window feature may require more testing, especially in some edge cases. When, after thorough testing, you believe this works in your workflow, feel free to deploy it, and please let us know about your success or any issues you might encounter.
|
||||
This value determines when Setup Manager should launch. There are two values: `enrollment` (default) and `loginwindow`. When set to `enrollment` Setup Manager will launch immediately when its installation package is installed. This is the setting to use for automated device enrollment (without Auto Advance) and user-initiated enrollment.
|
||||
|
||||
This value determines when Setup Manager should launch. There are two values: `enrollment` (default) and `loginwindow`. When set to `enrollment` Setup Manager will launch immediately when the pkg is installed. This is the setting to use for automated device enrollment (without Auto Advance) and user-initiated enrollment.
|
||||
|
||||
When the `runAt` value is set to `loginwindow` Setup Manager will launch only when the login window is shown. This is useful for fully automated enrollments using Auto Advance.
|
||||
When the `runAt` value is set to `loginwindow` Setup Manager will launch only when the login window is shown. This is useful for fully automated enrollments using Auto Advance and some workflows involving Jamf Connect or similar tools.
|
||||
|
||||
A setting of `loginwindow` will only work with enrollment setups that eventually end on the login window (i.e. a user has to be created automatically, the device is bound to a directory, etc).
|
||||
|
||||
@@ -119,7 +143,7 @@ When this key exists, Setup Manager will show a "Help" button (a circled questio
|
||||
|
||||
#### `accentColor`
|
||||
|
||||
(String or Dict, optional, default: system blue, dark mode)
|
||||
(String or Dict, optional, localized, dark mode, default: system blue)
|
||||
|
||||
Sets the accent color for buttons, progress bar, SF Symbol icons, and other UI elements. You can use this to match branding. Color is encoded as a six digit hex code, e.g. `#FF0088`.
|
||||
|
||||
@@ -130,7 +154,16 @@ Example:
|
||||
<string>#FF00AA</string>
|
||||
```
|
||||
|
||||
If you want different accent colors depending on whether the system is in light or dark mode, provide a `dict` with two keys, for `light` and `dark` mode:
|
||||
You can also use named system colors. (See ['Defining Colors'](#defining-colors) for a full list.)
|
||||
|
||||
Example:
|
||||
|
||||
```xml
|
||||
<key>accentColor</key>
|
||||
<string>##green</string>
|
||||
```
|
||||
|
||||
If you want different accent colors depending on whether the system is in light or dark mode, provide a `dict` with two keys, for `light` and `dark` mode: (Note: named system colors adapt automatically)
|
||||
|
||||
Example:
|
||||
|
||||
@@ -144,11 +177,19 @@ Example:
|
||||
</dict>
|
||||
```
|
||||
|
||||
#### `tileColor`
|
||||
|
||||
(String or Dict, optional, localized, dark mode, default: `##background`, v1.4)
|
||||
|
||||
Sets the action tile background color for all action tiles, unless the value is overridden by an individual action's `tileColor` key. You can use [color designators](#defining-colors). See the action level [`tileColor`](#tilecolor-1) for details.
|
||||
|
||||
When you set the `tileColor` to `##automatic`, Setup Manager computes an average color from the tile's `icon`. For `symbol` icons, the default background will be used.
|
||||
|
||||
#### `finalCountdown`
|
||||
|
||||
(Number/integer, optional, default: `60`)
|
||||
|
||||
This key changes the duration (in seconds) of the "final countdown" before the app automatically performs the `finalAction` (continue or shut down). Set to `-1` (or any negative number) to disable automated execution.
|
||||
This key changes the duration (in seconds) of the "final countdown" before the app automatically performs the `finalAction`. Set to `-1` to disable automated execution.
|
||||
|
||||
Example:
|
||||
|
||||
@@ -170,13 +211,16 @@ Disable the countdown:
|
||||
|
||||
This key sets the action and label for the button shown when Setup Manger has completed.
|
||||
|
||||
There are three options:
|
||||
There are four options:
|
||||
- `continue`: (default) merely quits Setup Manager and allows the user to continue (probably Setup Assistant or login window)
|
||||
- `restart`: restarts the Mac
|
||||
- `shut down`: (no space!) shuts down the Mac
|
||||
- `shutdown`: (no space!) shuts down the Mac
|
||||
- `none`: no button shown. (see note below)
|
||||
|
||||
**Warning:** `restart` and `shutdown` options will force their action immediately. If a user is logged in (after user-initiated enrollment), they may lose data from open, unsaved documents.
|
||||
|
||||
**Note on `none`:** the `none` option exists for workflows where the restart or continue is controlled by a process other than Setup Manager. For example, when installing additional software with a `finishedScript` or `finishedTrigger` which forces a restart. Having a `continue` or `restart` button would be confusing and might interrupt the installation in the finished process. However, having no button to end Setup Manager at all, might leave the user 'stuck' there, so be sure to always restart or kill Setup Manager. You can always use the keyboard shortcut `shift-control-command-E` to quit Setup Manager.
|
||||
|
||||
This is also the action that is performed when the `finalCountdown` timer runs out.
|
||||
|
||||
When the `DEBUG` preference is set, `shutdown` or `restart` will merely quit/continue.
|
||||
@@ -188,11 +232,48 @@ Example:
|
||||
<string>shutdown</string>
|
||||
```
|
||||
|
||||
#### `finishedScript`
|
||||
|
||||
(String, optional)
|
||||
|
||||
A full path to a script file which will be executed _after_ Setup Manager has finished its workflow. This process runs independently of Setup Manager, so it can run installers or scripts that affect Setup Manager.
|
||||
|
||||
The script has to fulfill these criteria to be executed:
|
||||
|
||||
- owner: `root`, group: `wheel`
|
||||
- executable bit set
|
||||
- not writable for group or other (file mode `755` or `555`)
|
||||
- no quarantine flag attached
|
||||
|
||||
The output of the finished script and trigger will be logged to `/private/var/log/setupManagerFinished.log`.
|
||||
|
||||
Example:
|
||||
|
||||
```xml
|
||||
<key>finishedScript</key>
|
||||
<string>/Library/Management/finishedScript.sh</string>
|
||||
```
|
||||
|
||||
#### `finishedTrigger`
|
||||
|
||||
(String, optional, Jamf Pro only)
|
||||
|
||||
A custom policy trigger which will be executed _after_ Setup Manager has finished its workflow. This process runs independently of Setup Manager, so it can run installers or scripts that affect Setup Manager.
|
||||
|
||||
The output of the finished script and trigger will be logged to `/private/var/log/setupManagerFinished.log`.
|
||||
|
||||
Example:
|
||||
|
||||
```xml
|
||||
<key>finishedTrigger</key>
|
||||
<string>setup_manager_finished</string>
|
||||
```
|
||||
|
||||
#### `totalDownloadBytes`
|
||||
|
||||
(Integer, opitonal, default: 1000000000 or 1GB, v0.8)
|
||||
(Integer, optional, default: 1000000000 or 1GB, v0.8)
|
||||
|
||||
Use this value to provide an estimate for the total size of all items that will be downloaded. Setup Manager will display and estimated download time for this sum in the "About this Mac..." popup window.
|
||||
Use this value to provide an estimate for the total size of all items that will be downloaded. Setup Manager will display an estimated download time for this sum in the "About this Mac..." popup window.
|
||||
|
||||
Example:
|
||||
|
||||
@@ -201,32 +282,47 @@ Example:
|
||||
<integer>4500000000</integer>
|
||||
```
|
||||
|
||||
#### `jssID`
|
||||
#### `computerID`
|
||||
|
||||
(String, Jamf Pro only)
|
||||
|
||||
Set this to `$JSSID` in the configuration profile and Setup Manager will be aware of its computer's id in Jamf Pro. It will be displayed in the 'About this Mac…' popup, when clicked with the option key.
|
||||
When filled with the correct payload variable, this provides the identifier for the computer to Setup Manager. It will be displayed in the in the 'About this Mac…' popup, when clicked with the option key.
|
||||
|
||||
Example:
|
||||
For Jamf Pro, the value for `computerID` should be `$JSSID`. For Jamf School, it should be `%udid%.
|
||||
|
||||
Examples:
|
||||
|
||||
Jamf Pro:
|
||||
|
||||
```xml
|
||||
<key>jssID</key>
|
||||
<key>computerID</key>
|
||||
<string>$JSSID</string>
|
||||
```
|
||||
|
||||
#### `userID`
|
||||
Jamf School:
|
||||
|
||||
```xml
|
||||
<key>computerID</key>
|
||||
<string>%udid%</string>
|
||||
```
|
||||
|
||||
Note: up to version 1.3, this key was called `jssID`. This was changed in v1.4 for Jamf School support. The old key `jssID` is deprecated.
|
||||
|
||||
#### `enrollmentUserID`
|
||||
|
||||
(String, Jamf Pro only)
|
||||
|
||||
Set this to `$EMAIL` in the configuration profile. This communicates the user who logged in to customized enrollment to Setup Manager. This can be used together with the `userEntry.showForUserIDs` key to control which users see the user entry UI.
|
||||
Set this to `$EMAIL` in the configuration profile. This communicates the user who logged in to customized enrollment to Setup Manager. This can be used together with the [`userEntry.showForUserIDs`](#conditionally-show-the-user-entry-for-certain-users) key to control which users see the user entry UI.
|
||||
|
||||
Example:
|
||||
|
||||
```xml
|
||||
<key>userID</key>
|
||||
<key>enrollmentUserID</key>
|
||||
<string>$EMAIL</string>
|
||||
```
|
||||
|
||||
Note: in Setup Manager v1.3 and earlier, this key was called `userID`. The name changed in v1.4 to avoid confusion with `userEntry.userID` which serves a different purpose and can have different values. The top-level `userID` key will keep working with the same function for now. If both keys are given, `enrollmentUserID` will take precedence. The top-level `userID` key will be removed in a future version.
|
||||
|
||||
#### `computerNameTemplate`
|
||||
|
||||
(String, Jamf Pro only, substitutions)
|
||||
@@ -291,6 +387,52 @@ Example:
|
||||
|
||||
When debug mode is enabled, you can set the `simulateMDM` preference key to `Jamf Pro` or `Jamf School`. This allows you to do test runs on un-enrolled Macs.
|
||||
|
||||
#### `actionOutputLogging`
|
||||
|
||||
(string, optional, default: `error`)
|
||||
|
||||
This key controls whether the output of actions is written to the Setup Manager log file.
|
||||
|
||||
There are three options:
|
||||
- `always`: output and exit code are always written to the log file
|
||||
- `error`: (default) output and exit code are only written on errors
|
||||
- `never`: output and exit are never written to the log file
|
||||
|
||||
Setup Manager's log window will always show the output, regardless of this setting.
|
||||
|
||||
Example:
|
||||
|
||||
```xml
|
||||
<key>actionOutputLogging</key>
|
||||
<string>always</string>
|
||||
```
|
||||
|
||||
#### `networkQualityCheck`
|
||||
|
||||
(Bool, optional, default: `true`, v1.4)
|
||||
|
||||
Set this key to false to suppress the network quality check. This is useful in classroom or lab environments where multiple Macs are re-enrolled at similar times to protect network bandwidth.
|
||||
|
||||
Example:
|
||||
|
||||
```xml
|
||||
<key>networkQualityCheck</key>
|
||||
<false/>
|
||||
```
|
||||
|
||||
#### `finishedMessage`
|
||||
|
||||
(String, optional, localized, substitutions, markdown, v1.4)
|
||||
|
||||
Custom message when Setup Manager workflow is complete.
|
||||
|
||||
Example:
|
||||
|
||||
```xml
|
||||
<key>finishedMessage</key>
|
||||
<string>**Finished** – _Enjoy your %model%!_</string>
|
||||
```
|
||||
|
||||
## Actions
|
||||
|
||||
All actions should have these keys:
|
||||
@@ -305,10 +447,61 @@ The label is used as the name of the action in display.
|
||||
|
||||
(String, optional, localized, dark mode)
|
||||
|
||||
The [icon source](#icon-sources) used for the display of the label. Different types of actions will have different default icons, which are used when no `icon` key is present. The icons will be scaled to fit 64x64 pixels (or 128x128 @2x).
|
||||
The [icon source](#icon-sources) used for the display of the label. Different types of actions will have different default icons, which are used when no `icon` key is present. The icons will be scaled to fit 120x120 pixels.
|
||||
|
||||
There are several different types of actions, and these are defined by additional keys. These keys will be on the same level as the keys above.
|
||||
|
||||
**Note on icon margins:** when you use a path to an app for the icon, or when you use an icon generated by copying the icon from an app in Finder or by a tools such as the [SAP Icon Generator](https://github.com/SAP/macOS-icon-generator), there will be a margin around the icon. Since these are very common ways of getting icons, the layout of the icons in the action tile is designed around the assumption that there will be a margin. Icons without such a margin will look quite big fill most of the space available in the tile.
|
||||
|
||||
#### `tileColor`
|
||||
|
||||
(String, optional, dark mode, v1.4)
|
||||
|
||||
This key sets this action's' background color. You can use [color designators](#defining-colors).
|
||||
|
||||
`tileColor` values set on individual actions will override the top-level `tileColor`.
|
||||
|
||||
Example:
|
||||
|
||||
```xml
|
||||
<key>tileColor</key>
|
||||
<string>#FF00AA</string>
|
||||
```
|
||||
|
||||
```xml
|
||||
<key>tileColor</key>
|
||||
<string>##gray</string>
|
||||
```
|
||||
|
||||
Set the key to an empty value or `##background` to use the default window background color instead.
|
||||
|
||||
|
||||
```xml
|
||||
<key>tileColor</key>
|
||||
<string/>
|
||||
```
|
||||
|
||||
```xml
|
||||
<key>tileColor</key>
|
||||
<string>##background</string>
|
||||
```
|
||||
|
||||
When you set the `tileColor` to `##automatic`, Setup Manager computes an average color from tile's `icon`. For `symbol` icons, the default background will be used.
|
||||
|
||||
```xml
|
||||
<key>tileColor</key>
|
||||
<string>##automatic</string>
|
||||
```
|
||||
|
||||
Set `tileColor` to `##clear` to remove the tile background. This works best when `hideActionLabels` is set to false.
|
||||
|
||||
```xml
|
||||
<key>tileColor</key>
|
||||
<string>##clear</string>
|
||||
<key>hideActionLabels</key>
|
||||
<false/>
|
||||
```
|
||||
|
||||
### Shell Command
|
||||
|
||||
#### `shell`
|
||||
@@ -349,6 +542,20 @@ Example:
|
||||
</dict>
|
||||
```
|
||||
|
||||
This example is the equivalent of this command line:
|
||||
|
||||
```
|
||||
sudo systemsetup -setTimeZone Europe/Amsterdam
|
||||
```
|
||||
|
||||
Notes: to break the command in to its components
|
||||
|
||||
- full path to the command
|
||||
- arguments are split into the `arguments` array, one string entry per argument, no quoting or backslash escaping
|
||||
- if the command contains a `&` it needs to be escaped with `&`
|
||||
- shell constructs such as substitution (e.g `$SHELL`), redirection (e.g `&2>1`)
|
||||
- `sudo` won't work in this context, instead set `requiresRoot` to true
|
||||
|
||||
### Jamf Policy Trigger
|
||||
|
||||
#### `policy`
|
||||
@@ -358,7 +565,7 @@ Example:
|
||||
This will run the Jamf Pro policy or polices with the given trigger name. This is the equivalent of running
|
||||
|
||||
```
|
||||
jamf policy -event <triggername> -verbose -forceNoRecon -doNotRestart -noInteraction
|
||||
jamf policy -event <triggername> -verbose -forceNoRecon -doNotRestart -noInteraction -skipAppUpdates
|
||||
```
|
||||
|
||||
Note: Jamf Pro policies can do a lot of different things and fail in many different ways. Setup Manager does _not_ check for all possible failure modes. It only checks for failed installer pkgs and policy scripts that return non-zero exit codes, which should cover most uses of policies for initial deployment.
|
||||
@@ -376,6 +583,20 @@ Example:
|
||||
</dict>
|
||||
```
|
||||
|
||||
Note: You can trigger policies attached to "Recurring Check-in" by leaving the string value empty:
|
||||
|
||||
|
||||
```xml
|
||||
<dict>
|
||||
<key>icon</key>
|
||||
<string>symbol:arrow.trianglehead.2.clockwise.rotate.90</string>
|
||||
<key>label</key>
|
||||
<string>Check-in</string>
|
||||
<key>policy</key>
|
||||
<string/>
|
||||
</dict>
|
||||
```
|
||||
|
||||
### Watch Path
|
||||
|
||||
#### `watchPath`
|
||||
@@ -476,9 +697,9 @@ Example:
|
||||
|
||||
### Installomator
|
||||
|
||||
This will run [Installomator](https://github.com/Installomator/Installomator) to install a given label.
|
||||
Setup Manager includes the [Installomator](https://github.com/Installomator/Installomator) script to simplify installations. This action will run [Installomator](https://github.com/Installomator/Installomator) to install a given label.
|
||||
|
||||
Note: by default, Setup manager will add `NOTIFY=silent` to the arguments to suppress notfications. You can override this in the `arguments`.
|
||||
Note: by default, Setup manager will add `NOTIFY=silent` to the arguments to suppress notifications. You can override these variables and add more with the `arguments` key.
|
||||
|
||||
#### `installomator`
|
||||
|
||||
@@ -505,6 +726,21 @@ Example:
|
||||
</dict>
|
||||
```
|
||||
|
||||
with arguments:
|
||||
|
||||
```xml
|
||||
<dict>
|
||||
<key>label</key>
|
||||
<string>Example App</string>
|
||||
<key>installomator</key>
|
||||
<string>example</string>
|
||||
<key>arguments</key>
|
||||
<array>
|
||||
<string>downloadURL=https://example.com/alternativeURL</string>
|
||||
</array>
|
||||
</dict>
|
||||
```
|
||||
|
||||
|
||||
## Icon Sources
|
||||
|
||||
@@ -561,13 +797,35 @@ Note that the availability and appearance of SF Symbols may vary with the OS ver
|
||||
<string>symbol:clock</string>
|
||||
```
|
||||
|
||||
### Color
|
||||
|
||||
(v1.4)
|
||||
|
||||
When the icon source starts with `#`, Setup Manager will interpret it as a hex color.
|
||||
|
||||
You can use hex color notation with three digits, e.g `#0f0` or six digits, e.g. `#f900a2`.
|
||||
|
||||
You can also use named system colors with two leading `##`, e.g `##yellow` or `##primary`.
|
||||
|
||||
(See ['Defining Colors'](#defining-colors) for details.)
|
||||
|
||||
```xml
|
||||
<key>background</key>
|
||||
<string>##white</string>
|
||||
```
|
||||
|
||||
```xml
|
||||
<key>background</key>
|
||||
<string>#aaa</string>
|
||||
```
|
||||
|
||||
### Dark Mode
|
||||
|
||||
Note: after enrollment, over Setup Assistant, the system is always in light mode. This is only relevant when you use Setup Manager after user-initiated enrollment
|
||||
Note: after enrollment, over Setup Assistant, the system is always in light mode. This is only relevant when you use Setup Manager after user-initiated enrollment or launch it otherwise over user space.
|
||||
|
||||
To provide alternative images for dark or light mode, change the `string` defining the image to a dictionary with a `dark` and a `light` key. This works with the `background`, `icon`, and each action's `icon`. This also works with the `accentColor` key.
|
||||
|
||||
Note that Setup Manager does _not_ monitor the appearance mode, so if it changes _while_ Setup Manager is running, things will not update consistently.
|
||||
Setup Manager does _not_ monitor the appearance mode, so if it changes _while_ Setup Manager is running, things will not update consistently.
|
||||
|
||||
Example:
|
||||
|
||||
@@ -584,7 +842,7 @@ Example:
|
||||
|
||||
## User Entry
|
||||
|
||||
You can enable user entry for the following keys:
|
||||
You can enable user entry for the following fields:
|
||||
|
||||
- `userID`
|
||||
- `email`
|
||||
@@ -600,6 +858,8 @@ You can enable user entry for the following keys:
|
||||
|
||||
Any of the fields will only be shown when its key exists. If you were to create an empty `userEntry` dict, you get an empty user input screen with a 'Save' button - not a good user experience.
|
||||
|
||||
For each field, you need to provide at least one of `default`, `placeholder`, or `options`.
|
||||
|
||||
`userID` and `email` can be somewhat confusing and depending on which Cloud directory you have configured in Jamf Pro, you may need one or the other or both. Because of this Setup Manager 1.1 and older would only prompt for 'User email' and set both `userID` and `email` from that value. To maintain compatibility with this behavior, Setup Manager will continue to set _both_ `userID` and `email` when only one of the two values is requested and entered. If you request both fields, both will be set individually in the recon.
|
||||
|
||||
|
||||
@@ -607,6 +867,9 @@ Any of the fields will only be shown when its key exists. If you were to create
|
||||
|
||||
Data from user entry is written, together with some other data to a file when Setup Manager reaches a `waitForUserEntry` action and again when it finishes. The file is stored at `/private/var/db/SetupManagerUserData.txt`. [More details.](Docs/Extras.md#user-data-file)
|
||||
|
||||
|
||||
### Keys
|
||||
|
||||
#### `default`
|
||||
|
||||
(String, localized)
|
||||
@@ -759,7 +1022,7 @@ In this example, the 'Room' field will be shown in Setup Manager with the label
|
||||
|
||||
You can configure Setup Manager to only show the user entry section when specified users have authenticated in enrollment customization. This enables workflows, where certain users (techs and admins) get the option to re-assign the device to another user, but other users don't see the option.
|
||||
|
||||
For this, you need to setup the top-level `userID` to receive the `$EMAIL` variable. This will communicate to SetupManager the user who logged in with customized enrollment. Then you add key `showForUserIDs` with an array of user emails to the `userEntry` dict. When both `userID` and `userEntry.showForUserIDs` are set, the user entry UI will only show for the listed users.
|
||||
For this, you need to setup the top-level `enrollmentUserID` to receive the `$EMAIL` variable. This will communicate to SetupManager the user who logged in with customized enrollment. Then you add key `showForUserIDs` with an array of user emails to the `userEntry` dict. When both `enrollmentUserID` and `userEntry.showForUserIDs` are set, the user entry UI will only show for the listed users.
|
||||
|
||||
#### `showForUserIDs`
|
||||
|
||||
@@ -784,7 +1047,7 @@ Example:
|
||||
<string>\S+\.\S+@example.com</string>
|
||||
</dict>
|
||||
</dict>
|
||||
<key>userID</key>
|
||||
<key>enrollmentUserID</key>
|
||||
<string>$EMAIL</string>
|
||||
```
|
||||
|
||||
@@ -824,6 +1087,10 @@ Example:
|
||||
|
||||
Setup Manager can send web hooks to servers and services to trigger workflows there. You can read [details on how to configure and use WebHooks here](Docs/Webhooks.md).
|
||||
|
||||
## Network Connectivity
|
||||
|
||||
Setup Manager can check and display the network status and connectivity to a list of hosts. You can read [the details on how to configure this here](Docs/Network.md).
|
||||
|
||||
## Localization
|
||||
|
||||
The app will pick up the user choice of the UI language for the interface elements. (Table of currently available languages below.) The app will fall back to English for other language choices.
|
||||
@@ -886,17 +1153,23 @@ The following keys can be localized:
|
||||
- `message`
|
||||
- `url`
|
||||
|
||||
Use these two-letter codes for these languages:
|
||||
### Network Check
|
||||
|
||||
- `label`
|
||||
|
||||
Use these codes for these languages:
|
||||
|
||||
| Language | two-letter code |
|
||||
|--------------------|-----------------|
|
||||
| English | en (default) |
|
||||
| English (UK) | en-GB |
|
||||
| Dutch (Nederlands) | nl |
|
||||
| French | fr |
|
||||
| German | de |
|
||||
| Italian | it |
|
||||
| Hebrew | he |
|
||||
| Italian | it |
|
||||
| Norwegian | nb |
|
||||
| Polish | pl |
|
||||
| Spanish | es |
|
||||
| Swedish | sv |
|
||||
|
||||
@@ -951,3 +1224,68 @@ These keys can use markdown:
|
||||
|
||||
- `message`
|
||||
- Help: `message`
|
||||
|
||||
## Defining Colors
|
||||
|
||||
Colors are defined with strings in the profile.
|
||||
|
||||
When the icon source starts with `#`, Setup Manager will interpret it as a hex color.
|
||||
|
||||
You can use hex color notation with three digits, e.g `#0f0` or six digits, e.g. `#f900a2`.
|
||||
|
||||
Example:
|
||||
|
||||
```xml
|
||||
<key>accentColor</key>
|
||||
<string>#FF00AA</string>
|
||||
```
|
||||
|
||||
(v1.4) You can also use named system colors with two leading `##`, e.g `##yellow` or `##primary`. Available color names are:
|
||||
|
||||
```
|
||||
primary primary text color, black in light mode, white in dark mode
|
||||
secondary slightly muted variant of primary
|
||||
accentColor color used for controls, set with `accentColor`
|
||||
background system window background color
|
||||
clear no background/transparent (1)
|
||||
black (1)
|
||||
blue
|
||||
brown
|
||||
cyan
|
||||
gray
|
||||
green
|
||||
indigo
|
||||
mint
|
||||
orange
|
||||
pink
|
||||
purple
|
||||
red
|
||||
teal
|
||||
white (1)
|
||||
yellow
|
||||
```
|
||||
|
||||
(1) All colors will automatically adapt to dark or light mode, _except_ `clear`, `black`, and `white`.
|
||||
|
||||
Example:
|
||||
|
||||
```xml
|
||||
<key>accentColor</key>
|
||||
<string>##green</string>
|
||||
```
|
||||
|
||||
### Dark mode
|
||||
|
||||
If you want different accent colors depending on whether the system is in light or dark mode, provide a `dict` with two keys, for `light` and `dark` mode: (Note: most named system colors adapt automatically)
|
||||
|
||||
Example:
|
||||
|
||||
```xml
|
||||
<key>accentColor</key>
|
||||
<dict>
|
||||
<key>dark</key>
|
||||
<string>#FF00AA</string>
|
||||
<key>light</key>
|
||||
<string>#AA0055</string>
|
||||
</dict>
|
||||
```
|
||||
|
||||
@@ -1,5 +1,21 @@
|
||||
# Extras and Notes
|
||||
|
||||
|
||||
## Keyboard Shortcuts
|
||||
|
||||
Note that the Setup Manager window does not activate to receive keystrokes automatically when running over Setup Manager. You have to click in the Setup Manager window first.
|
||||
|
||||
| Shortcut | Action |
|
||||
| ----------------------- | ------ |
|
||||
| shift-control-command E | ["exit"/quit Setup Manager](#Quit), use only in emergencies as it will leave installations in an indeterminate state |
|
||||
| command-L | open [Log window](#Logging) |
|
||||
| command-B | toggle Battery status icon in Setup Manager window |
|
||||
| command-N | toggle [Network status icon](Network.md) in Setup Manager window |
|
||||
| space | show [serial number bar code window](#scannable-serial-number-barcode) |
|
||||
| i | show "About this Mac" popup |
|
||||
| h | show "Help" popup, when present |
|
||||
| hold option key when clicking "About this Mac" | shows more info |
|
||||
|
||||
## Custom JSON Schema for Jamf Pro
|
||||
|
||||
- create a new profile
|
||||
@@ -15,7 +31,11 @@ The custom schema does not contain all keys and options available in the [config
|
||||
|
||||
When you reach the limits of the custom schema, use the XML it generates as a starting to building a custom XML.
|
||||
|
||||
Note that the custom schema can become confused when you switch between enrollment action types and you will need to clean up extra empty fields.
|
||||
Note that the custom schema can become confused when you switch between enrollment action types and you will need to clean up extra empty fields. It is best to delete the action type you don't need any more and create a new action of the desired type.
|
||||
|
||||
## iMazing Profile Editor
|
||||
|
||||
There is also a manifest for Setup Manager in [iMazing Profile Editor](https://imazing.com/profile-editor).
|
||||
|
||||
## Quit
|
||||
|
||||
@@ -23,7 +43,30 @@ The command-Q keyboard shortcut to quit the app is disabled. Use `shift-control-
|
||||
|
||||
## Logging
|
||||
|
||||
Setup Manager logs to `/Library/Logs/Setup Manager.log`. While Setup Manager is running you can open a log window with command-L.
|
||||
While Setup Manager is running you can open a log window with command-L.
|
||||
|
||||
There are two or three tabs, one for the main Setup Manager log, one showing output from `/var/log/install.log`, one showing configuration profile installation and removal, and (Jamf Pro only) one tab showing output from `/var/log/jamf.log`. Some log tabs will be summarized to events relevant to the enrollment workflow. You can see the full log content by unchecking the 'Summarize' option.
|
||||
|
||||
Note that the extra logs (Install, Profiles, and Jamf) show events that were not initiated by Setup Manager. Nevertheless, these events can be relevant to your enrollment workflow.
|
||||
|
||||
These extra events will also appear in the Setup Manager log tab and log file, as well as the universal log entries. Having these events in context at the time they occur in the Setup Manager log is very helpful when trouble-shooting enrollment workflows.
|
||||
|
||||
Setup Manager logs to `/Library/Logs/Setup Manager.log`. There are four columns:
|
||||
|
||||
- timestamp (in ISO8601)
|
||||
- log level (default, error or fault)
|
||||
- category (general, install, network, profile, jamfpro)
|
||||
- message
|
||||
|
||||
To clean up the main log a little, Setup Manager will only write the output of actions to the Setup Manager log file when an error occurred. You can control this behavior with a new top-level preference key `actionOutputLogging`.
|
||||
|
||||
Setup Manager also logs to the macOS unified system log. The subsystem is `com.jamf.setupmanager`. You can use the `log` command line tool to read the log.
|
||||
|
||||
For example:
|
||||
|
||||
```
|
||||
sudo log show --last 30m --predicate 'subsystem="com.jamf.setupmanager"'
|
||||
```
|
||||
|
||||
## Debug mode
|
||||
|
||||
@@ -108,3 +151,47 @@ Setup Manager will unload and remove its LaunchAgent and LauchDaemon files upon
|
||||
|
||||
If you still want to remove Setup Manager after successful enrollment, there is [a sample uninstaller script in the Examples folder](../Examples/uninstall.sh).
|
||||
|
||||
## (Jamf Pro): Useful Smart Groups
|
||||
|
||||
You can create smart groups to coordinate installations of Configuration profiles. Some useful examples are:
|
||||
|
||||
### Setup Manager Installed
|
||||
|
||||
Criteria: 'Application Bundle ID' is `com.jamf.setupmanager`
|
||||
|
||||
You can use this smart group to scope or limit configuration profiles, Mac App Store/VPP apps, and Jamf App Installer apps. This way their installation will not occur immediately after enrollment, potentially slowing down the installation of essential Jamf Pro components and extending the "Getting Ready" phase.
|
||||
|
||||
### Setup Manager Done
|
||||
|
||||
Create an Extension attribute named "Setup Manager Done" with the script code:
|
||||
|
||||
```sh
|
||||
if [ -f "/private/var/db/.JamfSetupEnrollmentDone" ]; then
|
||||
echo "<result>done</result>"
|
||||
else
|
||||
echo "<result>incomplete</result>"
|
||||
fi
|
||||
```
|
||||
|
||||
Then create a Smart Group named "Setup Manager Done" with the criteria `"Setup Manager Done" is "done"`.
|
||||
|
||||
You can use this to scope configuration profiles and policies so that they are installed or run _after_ Setup Manager is complete.
|
||||
|
||||
## Running Scripts and Policies when Setup Manager finishes
|
||||
|
||||
Generally, you want to coordinate tasks, configurations, and installations with Setup Manager actions. However, in some situations the installations might interfere with the Setup Manager workflow itself. This is most relevant with software that needs to reload the login window process, which will also kill Setup Manager. (e.g Jamf Connect Login)
|
||||
|
||||
Setup Manager provides a LaunchDaemon which monitors the `.JamfEnrollmentSetupDone` flag file. It then launches a script or a custom Jamf Pro policy trigger. Since this LaunchDaemon runs independently from Setup Manager, so it can run installers or scripts that might quit login window or Setup Manager.
|
||||
|
||||
However, if you have set Setup Manager to automatically shut down or restart at the end, this will interrupt the finished script or policy, unless the automated delay is long enough. Use the [`finalAction`](../ConfigurationProfile.md#finalAction) value of `none` to remove the button and countdown from the Setup Manager UI. However, now it the responsibility of the finishing process to restart the Mac or quit the Setup Manager process, otherwise Setup Manager will keep blocking the UI.
|
||||
|
||||
The finished script or custom trigger are configured in the Setup Manager configuration profile, with the [`finishedScript`](../ConfigurationProfile.md#finishedScript) and [`finishedTrigger`](../ConfigurationProfile.md#finishedTrigger) keys.
|
||||
|
||||
The SetupManagerFinished daemon logs its output (and the output of the policy and scripts to `/private/var/log/setupManagerFinished.log`.
|
||||
|
||||
## macOS Version support
|
||||
|
||||
| Setup Manager | Minimum macOS | Platforms |
|
||||
|---------------|---------------|-------------------------|
|
||||
| up to 1.2.2 | 12.0 | Intel and Apple silicon |
|
||||
| 1.3 and later | 13.5 | Intel and Apple silicon |
|
||||
|
||||
73
Docs/FAQ.md
73
Docs/FAQ.md
@@ -8,15 +8,23 @@
|
||||
|
||||
Yes, use the top-level `background` key and point it to a local image file or a http URL to an image file. If you don't want custom branding, you can set `background` to `/System/Library/CoreServices/DefaultDesktop.heic` for the default image.
|
||||
|
||||
## Setup Manager is not launching after enrollment
|
||||
## Setup Manager is not launching after enrollment?
|
||||
|
||||
There can be many causes for this. A few common causes are:
|
||||
There can be many causes for this.
|
||||
|
||||
First, check whether the Setup Manager.app exists at `/Applications/Utilities/Setup Manager.app` and a Setup Manager log file gets created at `/Library/Logs/Setup Manager.log`. When the app and the log file exist, read the log file for errors and messages which should give you a hint as to what is going on. When you have no user account to log in, you can boot to Recovery to check on these files.
|
||||
|
||||
If neither of those files exist, then the download and/or installation of Setup Manager is failing or not occurring in the first place. A few common causes are:
|
||||
|
||||
- Jamf Pro: check that Setup Manager is added to your prestage and the package does not have the label "Availability pending" in Settings> Packages
|
||||
- Jamf Pro: do not install JamfConnect.pkg in prestage when you want to use Setup Manager. Install JamfConnect with Setup Manager instead
|
||||
- you need at least one of the 'Setup Assistant Options' in the prestage to be set to _not_ skip. Location Services or 'Choose your Look' are common choices that you generally want to leave up the user anyway. Otherwise, Setup Assistant may quit before Setup Manager can launch and do its actions.
|
||||
- Jamf Pro:
|
||||
- when using a distribution point other than Jamf Cloud Distribution Point, you need [to provide a manifest](https://appleshare.it/posts/use-manifest-file/)
|
||||
- check that Setup Manager is added to your Prestage and the package does **not** have the label "Availability pending" in Settings> Packages. Pending packages will not install during prestage. Wait a few minutes to see if the pending label updates
|
||||
- in Prestage > Enrollment Packages verify that the Package is added and the Distribution Point is set correctly (the DP resets to "none" when you remove the last enrollment package from Prestage, so this is easy to miss)
|
||||
- you can try deleting the Setup Manager pkg from Packages, re-uploading the package and re-adding it to the Prestage. (and verify that the Distribution Point is set correctly in the Prestage)
|
||||
- when the above steps do not remedy the issue, please engage Jamf Support.
|
||||
- when running at 'enrollment,' Setup Manager requires Setup Assistant to be running in the background. When you are using standard macOS user account creation, Setup Assistant will be showing that pane "behind" Setup Manager, so you should be fine. But if you are using Jamf Connect Login or a similar tool for account creation, you need at least one of the 'Setup Assistant Options' in the Prestage to be set to _not_ skip. 'Location Services' or 'Terms & Conditions' are a good choice that you generally want to leave up the user anyway. Otherwise, Setup Assistant may quit before Setup Manager can launch and do its actions.
|
||||
|
||||
## Does Setup Manager require Jamf Connect
|
||||
## Does Setup Manager require Jamf Connect?
|
||||
|
||||
No.
|
||||
|
||||
@@ -27,7 +35,7 @@ Setup Manager will run fine without Jamf Connect. You can even build 'single-tou
|
||||
- preinstall icon files with a custom package installer in prestage. Set the priority of the media/branding package lower than that for Setup Manager, or give the branding/media package a name that is alphabetically earlier than Setup Manager, so it installs before Setup Manager
|
||||
- use http(s) urls to the image files
|
||||
- you can host them on a web server/service that you have control over
|
||||
- you can add the icon as an icon for a Self Service policy in Jamf and then copy the url to the icon once uploaded
|
||||
- you can add the icon to a Self Service policy in Jamf and then copy the url to the icon once uploaded
|
||||
|
||||
|
||||
## What is happening during "Getting Ready" and "Finishing"?
|
||||
@@ -38,11 +46,33 @@ When enrolled into Jamf Pro, Setup Manager runs (among other things) a recon/Upd
|
||||
|
||||
You can open the log window (command-L) or review the [log file](Extras.md#logging) for detail for each step. Should Setup Manager stall during one of these steps, you can [quit](Extras.md#quit) out of Setup Manager and review the [log file](Extras.md#logging) after completing the setup.
|
||||
|
||||
## (Jamf Pro) Getting Ready is taking very long (several minutes). What is happening and can I do something to make it faster?
|
||||
|
||||
The "Getting Ready" phase prepares some steps and waits for all essential Jamf Pro components (the jamf binary, certificates, Jamf.app, etc.) to be installed and configured before starting with the actual enrollment workflow. Depending on the network connection this might take a while.
|
||||
|
||||
Note that you can see the individual steps and the timing for each step in the [Setup Manager log file](Extras.md#logging)].
|
||||
|
||||
Once Jamf Pro's enrollment workflow is complete, Setup Manager runs a full update inventory/recon. In general, if the recon takes a long time, you should review the inventory collection settings. Calculating home directory sizes and gathering fonts can take a lot of time and CPU power, and speed up things significantly when turned off, not just during enrollment with Setup Manager. You should also review extension attributes, for how long each one runs.
|
||||
|
||||
Mac App Store/VPP and Jamf App Installer apps that are scoped to the computer will also begin installing _immediately_ after enrollment. Since macOS will only perform one installation at a time, these might delay the installation of essential Jamf Pro components. You can create smart groups to defer these installations.
|
||||
|
||||
With Setup Manager 1.3 and higher, you can check whether apps are getting installed before Setup Manager starts the actions in the Setup Manager log.
|
||||
|
||||
|
||||
## Can I set the wallpaper/desktop picture or dock with Setup Manager?
|
||||
|
||||
The settings for the dock and wallpaper/desktop picture are _user_ settings. Since the user account usually does not yet exist when Setup Manager runs, you cannot affect those settings.
|
||||
|
||||
What you can do is run a script at login which sets the desktop (using [desktoppr](https://github.com/scriptingosx/desktoppr) ) or the dock (using [dockutil](https://github.com/kcrawford/dockutil) or a similar tool). You can use the Jamf Pro login trigger for this, or create a custom LaunchAgent or use [outset](https://github.com/macadmins/outset/)
|
||||
What you can do is run a script at login which sets the desktop (using [desktoppr](https://github.com/scriptingosx/desktoppr) ) or the dock (using [dockutil](https://github.com/kcrawford/dockutil) or a similar tool).
|
||||
|
||||
## If Setup Manager cannot do it, how can I run scripts at first login
|
||||
|
||||
There are several options:
|
||||
|
||||
- Jamf Pro: [Self Service macOS Onboarding](https://learn.jamf.com/en-US/bundle/jamf-pro-documentation-current/page/macOS_Onboarding.html)
|
||||
- Jamf Pro: [policy with a login trigger](https://learn.jamf.com/en-US/bundle/jamf-pro-documentation-current/page/Login_Events.html)
|
||||
- custom launch agent
|
||||
- [outset](https://github.com/macadmins/outset/)
|
||||
|
||||
## Can Setup Manager run at first login, rather than right after enrollment?
|
||||
|
||||
@@ -52,6 +82,33 @@ With Jamf Pro, you can set the Setup Manager pkg to install at the `login` trigg
|
||||
|
||||
This is not, however, the primary workflow for Setup Manager and not something that we will test or verify. We believe running right after enrollment over Setup Assistant is the preferable deployment.
|
||||
|
||||
With Jamf Pro, you should consider [macOS Onboarding in Self Service](https://learn.jamf.com/en-US/bundle/jamf-pro-documentation-current/page/macOS_Onboarding.html) or a [login trigger](https://learn.jamf.com/en-US/bundle/jamf-pro-documentation-current/page/Login_Events.html) instead.
|
||||
|
||||
## Installer or Policy Script is failing with access errors
|
||||
|
||||
For some policy scripts or installers it may be necessary to give the Setup Manager app Full Disk Access or some other exemptions with a PPPC Profile.
|
||||
|
||||
## Installomator actions are all failing
|
||||
|
||||
The log shows exit code 4, which means the download was rejected.
|
||||
|
||||
Installomator uses Gatekeeper to verify the downloads. When Gatekeeper is set to allow Mac App Store apps only it will reject all third party apps and installers and the verification will fail.
|
||||
|
||||
## Can I set Installomator variables?
|
||||
|
||||
Yes. The `installomator` action has an `arguments` key, which takes an array strings, one for each argument. With this, you can override variables in Installomator.
|
||||
|
||||
Example:
|
||||
|
||||
```xml
|
||||
<dict>
|
||||
<key>label</key>
|
||||
<string>Example App</string>
|
||||
<key>installomator</key>
|
||||
<string>example</string>
|
||||
<key>arguments</key>
|
||||
<array>
|
||||
<string>downloadURL=https://example.com/alternativeURL</string>
|
||||
</array>
|
||||
</dict>
|
||||
```
|
||||
|
||||
@@ -1,7 +1,5 @@
|
||||
# Jamf Pro: Run Setup Manager at Login Window
|
||||
|
||||
**Beta** _We believe the run at login window feature may require more testing, especially in some edge cases. When, after thorough testing, you believe this works in your workflow, feel free to deploy it, and please let us know about success or any issues you might encounter._
|
||||
|
||||
By default, Setup Manager launches as soon as the installation completes. You can defer launching Setup Manager to launch when the macOS Login Window appears, instead.
|
||||
|
||||
When the `runAt` key in the profile is set to `loginwindow`, Setup Manager will not launch immediately after installation but when Login Window appears. In combination with the 'AutoAdvance' feature for automated device enrollment, this allows for completely 'hands-off' enrollment and configuration workflows.
|
||||
|
||||
@@ -47,12 +47,12 @@ You can add more actions here. There are more types of actions available, you ca
|
||||
|
||||
## Scoping and Prestage
|
||||
|
||||
- Scope the configuration profile to the computers you want to run Setup Manager on
|
||||
- scope the configuration profile to the computers you want to run Setup Manager on
|
||||
- create a new Prestage or duplicate an existing one
|
||||
- Add the Setup Manager pkg and the configuration profile to the Prestage
|
||||
- if you have JamfConnect.pkg in the Prestage, remove it. You can later add an action to install JamfConnect using Setup Manager.
|
||||
- ensure that 'Automatically advance through Setup Assitant' is _disabled_
|
||||
- Have at least one Setup Assistant option _disabled_ (so that _is_ displayed)
|
||||
- add the Setup Manager pkg and the configuration profile to the Prestage
|
||||
- when installing and using Jamf Connect Login, ensure you have the latest version
|
||||
- ensure that 'Automatically advance through Setup Assistant' is _disabled_
|
||||
- have at least one Setup Assistant option which shows before user creation _disabled_ (so that _is_ displayed), we recommend the Location Services or Terms and Conditions pane
|
||||
- ensure your test Mac(s) is (are) assigned to the Prestage
|
||||
|
||||
## Wipe the Test Mac
|
||||
@@ -66,5 +66,5 @@ You can add more actions here. There are more types of actions available, you ca
|
||||
|
||||
- add more [actions](../ConfigurationProfile.md#actions) to Setup Manager, you can use more Jamf Pro policies, Installomator labels, or shell actions
|
||||
- automate computer naming with a [computer name template key](../ConfigurationProfile.md#computerNameTemplate)
|
||||
- add [a `help` section](../ConfigurationProfile.md#help) to let the user know what is going on
|
||||
- ideally automated deployments shouldn't require manual entry, but if necessary, you can configure a [user entry](../ConfigurationProfile.md#user-entry) section in the profile
|
||||
- optionally, add [a `help` section](../ConfigurationProfile.md#help) to let the user know what is going on
|
||||
- ideally automated deployments shouldn't require manual data entry, but if necessary, you can configure a [user entry](../ConfigurationProfile.md#user-entry) section in the profile
|
||||
|
||||
27
Docs/LaunchTracking.md
Normal file
27
Docs/LaunchTracking.md
Normal file
@@ -0,0 +1,27 @@
|
||||
# Launch and Completion Tracking in Setup Manager
|
||||
|
||||
Setup Manager sends tracking signals to a service we use to gather usage data. Currently (since 1.4) the service is [TelemetryDeck](https://telemetrydeck.com/). Older versions use [pendo.io](https://pendo.io).
|
||||
|
||||
In the ping, some data is transferred to the service, and the time and date of the signal are recorded.
|
||||
|
||||
This is the data in the signal:
|
||||
|
||||
- macOS system version and build
|
||||
- Setup Manager version
|
||||
- Device management service: Jamf Pro or Jamf School
|
||||
- A hash of the device management server url. This allows us to see how many devices are enrolled with a particular device management server, but we _cannot_ identify _which_ particular customer or server it is
|
||||
|
||||
Setup Manager version 1.4 adds the following info to the signal.
|
||||
|
||||
- Device information (model identifier, architecture)
|
||||
- Language and Region settings, preferred and actual
|
||||
- Color scheme choice: dark or light mode
|
||||
- Duration of the Setup Manager workflow
|
||||
- Running after enrollment, at login window, or over user space
|
||||
- Fatal errors (Setup Manager giving up completely, individual errors in actions are **not** tracked)
|
||||
|
||||
No signals are sent when `DEBUG` is set to `true`. The signal is sent to `nom.telemetrydeck.com`.
|
||||
|
||||
We use this data to determine the usage of Setup Manager and where to focus future development, so we appreciate when you let us gather this data.
|
||||
|
||||
You can suppress the tracking signal by setting the `PLEASE_DO_NOT_TRACK` boolean key to `true` in the configuration profile.
|
||||
87
Docs/Network.md
Normal file
87
Docs/Network.md
Normal file
@@ -0,0 +1,87 @@
|
||||
# Network Connectivity
|
||||
|
||||
Setup Manager can display the current network status in the top right corner of the main window.
|
||||
|
||||
By default, the icon will only appear when
|
||||
- there is no network connection or the connection is lost
|
||||
- Network Relay is configured
|
||||
- the `networkCheck` array is present in the profile, even when it is empty
|
||||
|
||||
You can always manually toggle the visibility of the network status icon with command-N.
|
||||
|
||||
The icon will show the network "globe" icon when the network is connected, the icon with a slash when it is disconnected, and the icon with a small shield when it is connected and Network Relay is configured.
|
||||
|
||||
You can click on the icon for more detailed information:
|
||||
- network connection name
|
||||
- IP addresses (IPv4 and IPv6, when present)
|
||||
- Network Bandwidth information (these take a while to appear, be patient)
|
||||
- When Network Relay is configured, it will show the connectivity to the HTTP3/QUIC and HTTP2 hosts
|
||||
- Connectivity to certain hosts
|
||||
- by default, the Jamf Server will be shown
|
||||
- You can add a list of custom hosts in the configuration profile
|
||||
|
||||
### `networkCheck`
|
||||
(array of dict, optional)
|
||||
|
||||
Provides a list of hosts to check connectivity to. These will be shown in the 'Connectivity' section in the network info pane.
|
||||
|
||||
Each dict in this array represents a check for a connection to a host. The dict can contain the following keys:
|
||||
|
||||
#### `host`
|
||||
|
||||
(string)
|
||||
|
||||
The host name, e.g. `host.example.com` (no url scheme) to test a connection to.
|
||||
|
||||
#### `port`
|
||||
|
||||
(integer, optional, default: `443`)
|
||||
|
||||
The port to test a connection to.
|
||||
|
||||
#### `protocol`
|
||||
|
||||
(string, optional, default: `tcp`)
|
||||
|
||||
The connection protocol to test: `tcp` or `udp`.
|
||||
|
||||
#### `label`
|
||||
|
||||
(string, localizable, optional)
|
||||
|
||||
A display label for the connection test.
|
||||
|
||||
Example:
|
||||
|
||||
```xml
|
||||
<key>networkCheck</key>
|
||||
<array>
|
||||
<dict>
|
||||
<key>host</key>
|
||||
<string>map.wandera.com</string>
|
||||
<key>label</key>
|
||||
<string>Intranet Maps</string>
|
||||
<key>port</key>
|
||||
<integer>443</integer>
|
||||
<key>protocol</key>
|
||||
<string>tcp</string>
|
||||
</dict>
|
||||
</array>
|
||||
```
|
||||
|
||||
Example: empty `networkCheck` array to force Network icon to always show
|
||||
|
||||
```xml
|
||||
<key>networkCheck</key>
|
||||
<array/>
|
||||
```
|
||||
|
||||
## Network Change logging
|
||||
|
||||
Setup Manager 1.3 adds logging for changes to network interfaces. It is possible that there will multiple entries in the log with regards to the same network change. Most changes logged will be neutral and should not affect your deployment negatively.
|
||||
|
||||
However, it is possible that changes to the network configuration of a device can influence the deployment workflow. Changes to network or Wi-Fi configurations and other network or security tools might disrupt the network connectivity during enrollment. This might interrupt or cancel downloads.
|
||||
|
||||
For example, when a configuration profile with the access information for a secure corporate Wifi is installed on the device, then the download access to required resources might change. Another example are security tools that might lead to restricted access for downloads (Installomator uses `curl` to download data, which might trigger security tools.)
|
||||
|
||||
Checking the log for network changes or outages during enrollment can be useful for troubleshooting.
|
||||
@@ -113,3 +113,52 @@ Use this webhook format in the Setup Manager profile:
|
||||
```
|
||||
|
||||
This `dict` replaces the simple `string` syntax.
|
||||
|
||||
### Slack
|
||||
|
||||
You can also [configure Slack to receive messages on webhook url](https://api.slack.com/messaging/webhooks).
|
||||
|
||||
Use this webhook format in the Setup Manager profile:
|
||||
|
||||
```xml
|
||||
<dict>
|
||||
<key>kind</key>
|
||||
<string>slack</string>
|
||||
<key>url</key>
|
||||
<string>--insert url from Slack here--</string>
|
||||
</dict>
|
||||
```
|
||||
|
||||
### Multiple webhooks
|
||||
|
||||
You can send multiple services per event:
|
||||
|
||||
```xml
|
||||
<key>webhooks</key>
|
||||
<dict>
|
||||
<key>finished</key>
|
||||
<array>
|
||||
<string>https://example.com/webhook-finish</string>
|
||||
<dict>
|
||||
<key>kind</key>
|
||||
<string>teams</string>
|
||||
<key>url</key>
|
||||
<string>--insert url from Teams Workflows here--</string>
|
||||
</dict>
|
||||
</array>
|
||||
<key>started</key>
|
||||
<array>
|
||||
<string>https://example.com/webhook-start</string>
|
||||
<dict>
|
||||
<key>kind</key>
|
||||
<string>teams</string>
|
||||
<key>url</key>
|
||||
<string>--insert url from Teams Workflows here--</string>
|
||||
</dict>
|
||||
</array>
|
||||
</dict>
|
||||
```
|
||||
|
||||
### Webhooks in Debug mode
|
||||
|
||||
Webhooks are generally _not_ sent when DEBUG is set to true. However, if you set a `DEBUG` key to `true` _inside_ the webhooks dictionary to true, webhooks will be sent, even when global DEBUG is enabled.
|
||||
|
||||
@@ -15,7 +15,7 @@
|
||||
<key>label</key>
|
||||
<dict>
|
||||
<key>de</key>
|
||||
<string>Zeitzone setzen</string>
|
||||
<string>Zeitzone einstellen</string>
|
||||
<key>en</key>
|
||||
<string>Set Time Zone</string>
|
||||
<key>es</key>
|
||||
@@ -28,6 +28,12 @@
|
||||
<string>Imposta il fuso orario</string>
|
||||
<key>nl</key>
|
||||
<string>Tijdzone instellen</string>
|
||||
<key>sv</key>
|
||||
<string>Ställ in tidszon</string>
|
||||
<key>nb</key>
|
||||
<string>Angi tidssone</string>
|
||||
<key>pl</key>
|
||||
<string>Ustal strefę czasową</string>
|
||||
</dict>
|
||||
<key>requiresRoot</key>
|
||||
<true/>
|
||||
@@ -91,6 +97,12 @@
|
||||
<string>Sii paziente mentre Setup Manager configura il tuo nuovo Mac.</string>
|
||||
<key>nl</key>
|
||||
<string>Even geduld terwijl Setup Manager je nieuwe Mac configureert.</string>
|
||||
<key>pl</key>
|
||||
<string>Prosimy o cierpliwość, podczas gdy Setup Manager konfiguruje Twojego nowego Maca.</string>
|
||||
<key>sv</key>
|
||||
<string>Ha tålamod medan Setup Manager konfigurerar din nya Mac.</string>
|
||||
<key>nb</key>
|
||||
<string>Vær tålmodig mens Setup Manager konfigurerer den nye Mac-en din.</string>
|
||||
</dict>
|
||||
<key>title</key>
|
||||
<dict>
|
||||
@@ -99,15 +111,21 @@
|
||||
<key>en</key>
|
||||
<string>Welcome!</string>
|
||||
<key>es</key>
|
||||
<string>¡Bienvenido!</string>
|
||||
<string>¡^[^[Bienvenido](inflect: true)](inflectionAlternative: 'Te damos la bienvenida')!</string>
|
||||
<key>fr</key>
|
||||
<string>Bienvenu!</string>
|
||||
<key>he</key>
|
||||
<string>ברוכים הבאים!</string>
|
||||
<key>it</key>
|
||||
<string>Benvenuto!</string>
|
||||
<string>^[Benvenuto](inflect: true, inflectionAlternative: "Ciao")!</string>
|
||||
<key>nl</key>
|
||||
<string>Welcom!</string>
|
||||
<key>pl</key>
|
||||
<string>Witamy!</string>
|
||||
<key>sv</key>
|
||||
<string>Välkommen</string>
|
||||
<key>nb</key>
|
||||
<string>Velkommen</string>
|
||||
</dict>
|
||||
<key>userEntry</key>
|
||||
<dict>
|
||||
|
||||
@@ -7,17 +7,21 @@
|
||||
export PATH=/usr/bin:/bin:/usr/sbin:/sbin
|
||||
|
||||
# Note:
|
||||
# Setup Manager creates a flag file at
|
||||
# Setup Manager creates flag and data files at
|
||||
#
|
||||
# /private/var/db/.JamfSetupStarted
|
||||
# /private/var/db/.JamfSetupEnrollmentDone
|
||||
# /private/var/db/SetupManagerUserData.txt
|
||||
#
|
||||
# when it completes successfully. This uninstall script
|
||||
# does NOT remove this file. When you re-install Setup
|
||||
# Manager after running this script, the flag file's
|
||||
# existence will suppress the launch of Setup Manager.
|
||||
# This uninstall script does NOT (yet) remove these files.
|
||||
#
|
||||
# Depending on your workflow needs, you may want to
|
||||
# uncomment the last line which removes the flag file.
|
||||
# When you re-install Setup Manager after running this script,
|
||||
# the `.JamfSetupEnrollmentDone` flag file's existence will
|
||||
# suppress the launch of Setup Manager.
|
||||
#
|
||||
# Depending on your workflow needs, you may want to preserve
|
||||
# or remove these files during un-installation. Uncomment the
|
||||
# respective `rm` lines at the end of this script.
|
||||
|
||||
appName="Setup Manager"
|
||||
bundleID="com.jamf.setupmanager"
|
||||
@@ -29,6 +33,11 @@ if [ "$(whoami)" != "root" ]; then
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if launchctl list | grep -q "$bundleID.finished" ; then
|
||||
echo "unloading launch daemon"
|
||||
launchctl unload /Library/LaunchDaemons/"$bundleID".finished.plist
|
||||
fi
|
||||
|
||||
if launchctl list | grep -q "$bundleID" ; then
|
||||
echo "unloading launch daemon"
|
||||
launchctl unload /Library/LaunchDaemons/"$bundleID".plist
|
||||
@@ -38,8 +47,16 @@ echo "removing files"
|
||||
rm -rfv "$appPath"
|
||||
rm -v /Library/LaunchDaemons/"$bundleID".plist
|
||||
rm -v /Library/LaunchAgents/"$bundleID".loginwindow.plist
|
||||
rm -v /Library/LaunchAgents/"$bundleID".finished.plist
|
||||
|
||||
echo "forgetting $bundleID pkg receipt"
|
||||
pkgutil --forget "$bundleID"
|
||||
|
||||
# uncomment depending on which files you need to remove or preserve
|
||||
|
||||
# rm -v /private/var/db/.JamfSetupStarted
|
||||
# rm -v /private/var/db/.JamfSetupEnrollmentDone
|
||||
# rm -v /private/var/db/SetupManagerUserData.txt
|
||||
|
||||
# always exit success regardless of exit code of above commands
|
||||
exit 0
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 617 KiB After Width: | Height: | Size: 804 KiB |
26
README.md
26
README.md
@@ -4,13 +4,18 @@
|
||||
|
||||
_"Every Assistant has a Manager"_
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Updates are published in the '[Releases](https://github.com/jamf-concepts/setup-manager/releases)' section of the repo. There you can also [download the latest pkg installer](https://github.com/jamf-concepts/setup-manager/releases/latest). You can subscribe to notifications for the repo using the 'Watch' button above.
|
||||
|
||||
Please report issues, feature requests [as an issue.](https://github.com/jamf-concepts/setup-manager/issues)
|
||||
Updates are published in the '[Releases](https://github.com/jamf/setup-manager/releases)' section of the repo. There you can also [download the latest pkg installer](https://github.com/jamf/setup-manager/releases/latest). You can subscribe to notifications for the repo using the 'Watch' button above.
|
||||
|
||||
We have opened the [discussions](https://github.com/jamf-concepts/setup-manager/discussions) area for questions and more generic feedback.
|
||||
Please report issues, feature requests [as an issue.](https://github.com/jamf/setup-manager/issues)
|
||||
|
||||
We have opened the [discussions](https://github.com/jamf/setup-manager/discussions) area for questions and more generic feedback.
|
||||
|
||||
There is also a [`#jamf-setup-manager`](https://macadmins.slack.com/archives/C078DDLKRDW) channel on the [MacAdmins Slack](https://macadmins.org).
|
||||
|
||||
@@ -30,7 +35,7 @@ Setup Manager provides:
|
||||
- zero-touch (user-driven)
|
||||
- single-touch (tech-driven)
|
||||
- user initiated enrollment
|
||||
- handsfree deployment with AutoAdvance (beta)
|
||||
- handsfree deployment with Auto Advance
|
||||
- customized branding
|
||||
- localized interface and localizable custom text
|
||||
- works with Jamf Pro and Jamf School
|
||||
@@ -42,11 +47,12 @@ Setup Manager provides:
|
||||
- zero-touch and user-initiated deployments (forthcoming)
|
||||
- [extra installations based on user data entry](Docs/JamfPro-TwoPhase.md)
|
||||
- [Single-touch workflow with user re-assignment using Jamf Connect](Docs/JamfProConnect-SingleTouch.md)
|
||||
- [handsfree deployment with AutoAdvance and Setup Manager at login window (beta)](Docs/JamfPro-LoginWindow.md)
|
||||
- [handsfree deployment with AutoAdvance and Setup Manager at login window](Docs/JamfPro-LoginWindow.md)
|
||||
- [Jamf School](Docs/JamfSchool-Setup.md)
|
||||
- [Extras and Notes](Docs/Extras.md)
|
||||
- [Frequently Asked Questions](Docs/FAQ.md)
|
||||
- [Webhooks](Docs/Webhooks.md)
|
||||
- [Network Connectivity Checks](Docs/Network.md)
|
||||
|
||||
## Configuration Profile
|
||||
|
||||
@@ -56,14 +62,14 @@ There is also a [custom schema for Jamf Pro](Docs/Extras.md#custom-json-schema-f
|
||||
|
||||
## Requirements
|
||||
|
||||
Setup Manager requires macOS 12.0.0 or higher. It will work only with Jamf Pro or Jamf School.
|
||||
Setup Manager requires macOS 13.5 or higher. It will work only with Jamf Pro or Jamf School.
|
||||
|
||||
## Known Issues
|
||||
|
||||
- Setup Manager will **_not_** launch at enrollment with Auto-Advance enabled, use the option to run at login window
|
||||
- Setup Manager may **_not_** launch or launch and quit quickly when you disable _all_ Setup Assistant screens, leave at least one Setup Assistant option enabled, or use the option to run at login window
|
||||
- Policies that are triggered by `enrollmentComplete` may delay or even disrupt Setup Manager running from Prestage/Automated Device Enrollment. Disable or unscope policies triggered by `enrollmentComplete` on devices using Setup Manager.
|
||||
- Setup Manager may **_not_** launch or launch and quit quickly when you disable _all_ Setup Assistant screens and skip user creation, leave at least one Setup Assistant option that shows _before_ the user creation enabled, or use the option to run at login window
|
||||
- Policies that are triggered by `enrollmentComplete` may delay or even disrupt Setup Manager running from Prestage/Automated Device Enrollment. Disable or un-scope policies triggered by `enrollmentComplete` on devices using Setup Manager.
|
||||
|
||||
---
|
||||
|
||||
Please report issues, feature requests, and feedback (positive and negative) [as an issue.](https://github.com/Jamf-Concepts/Setup-Manager/issues)
|
||||
Please report issues, feature requests, and feedback (positive and negative) [as an issue.](https://github.com/jamf/Setup-Manager/issues)
|
||||
|
||||
9
catalog-info.yaml
Normal file
9
catalog-info.yaml
Normal file
@@ -0,0 +1,9 @@
|
||||
apiVersion: backstage.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: setup-manager
|
||||
spec:
|
||||
type: application
|
||||
lifecycle: production
|
||||
owner: concepts
|
||||
system: jamf-concept-projects
|
||||
Reference in New Issue
Block a user