Skip to content

Commit dd25148

Browse files
scriptingosxscriptingosx
committed
Merge branch 'beta'
2 parents 9368026 + 552f8e7 commit dd25148

File tree

9 files changed

+527
-31
lines changed

9 files changed

+527
-31
lines changed

‎ChangeLog.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,151 @@
11
# Setup Manager - Change Log
22

3+
## 1.3
4+
(2025-07-08)
5+
6+
Notes added since 1.3beta are marked with '(release)'
7+
8+
### New Features
9+
- Logging
10+
- log output format has been cleaned up
11+
- Install log and Jamf Pro log (when available) can now be viewed in the Log window (#78, #130)
12+
- now also logs to macOS unified logging
13+
- new top-level default key to control action output logging
14+
- Network Monitoring
15+
- changes to network interfaces are now logged, see the Notes section for details (#15)
16+
- network status can be shown in the top-right corner of the Setup Manager window
17+
- 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
18+
- added [a specific webhook to send a message to Slack](Docs/WebHooks.md#Slack) (#104)
19+
- two new defaults keys `finishedScript` and `finishedTrigger` allow to run custom behavior when Setup Manager has finished
20+
- new option `none` for `finalAction` (#115)
21+
- (release) Polish localization (Thanks to @bsojka)
22+
23+
### Fixes and Improvements
24+
- Jamf Pro: improved monitoring for Jamf Pro to complete its setup after enrollment
25+
- webhook log entries correctly show status
26+
- added `-skipAppUpdates` option to list of options for Jamf Pro policy actions, this should avoid some false "error 57" reports
27+
- Jamf Pro policy will trigger 'Recurring Check-in' policies on empty string value
28+
- (release) added name for macOS Tahoe 26
29+
- (release) minor localization and UI fixes
30+
- (release) disabled some undesirable keyboard shortcuts (#125)
31+
- (release) arguments in `installomator` actions are now processed correctly
32+
- (release) output to log is flushed immediately to avoid truncation on restart/shutdown (#129)
33+
- (release) MDM Server address shown in extended "About this Mac" (#127)
34+
35+
### Deprecations and Removals
36+
- (1.3) the minimum macOS requirement for Setup Manager is now macOS 13.5
37+
- (1.2) `showBothButtons` option removed and non-functional, there will always be just one final action button displayed
38+
- 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)
39+
40+
### Notes
41+
42+
#### Logging
43+
44+
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:
45+
46+
- timestamp (in ISO8601)
47+
- log level (default, error or fault)
48+
- category (general, install, network, jamfpro)
49+
- message
50+
51+
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.
52+
53+
For example:
54+
55+
```
56+
sudo log show --last 30m --predicate 'subsystem="com.jamf.setupmanager"'
57+
```
58+
59+
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`.
60+
61+
#### Installation and Jamf Pro logs and summaries
62+
63+
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.
64+
65+
Note that both logs will show events that were not initiated by Setup Manager. Nevertheless, these events may be relevant to your enrollment workflow.
66+
67+
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.
68+
69+
#### Network change logging
70+
71+
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.
72+
73+
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.)
74+
75+
Checking the log for network changes or outages during enrollment can be useful for troubleshooting.
76+
77+
#### Network Status icon/menu
78+
79+
Network status can also show with a new icon in the top-right corner of the Setup Manager window.
80+
81+
Note that Network Relay will only protect traffic to certain configured servers and services, not all traffic.
82+
83+
By default, the network icon will _not_ be shown. You can activate it manually with the command-N keystroke.
84+
85+
When you click on the Network status icon, a popup will show:
86+
- the current active network interface
87+
- IPv4 and IPv6 addresses
88+
- download and upload bandwidth (will take a while to appear)
89+
- Network Relay hosts (when network relay profile is present)
90+
- list of additional custom hosts, configured in the profile
91+
92+
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.
93+
94+
Seen["Network Connectivity"](https://github.com/jamf/Setup-Manager/Docs/Network.md) for more detail.
95+
96+
#### Finished Script and Trigger
97+
98+
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).
99+
100+
There are two keys relevant for this: `finishedScript` and `finishedTrigger`.
101+
102+
See ["Running Scripts and Policies when Setup Manager finishes"](https://github.com/jamf/Setup-Manager/Docs/Extras.md#running-scripts-and-policies-when-setup-manager-finishes) for detail.
103+
104+
## v1.3beta
105+
(2025-05-27)
106+
107+
### New Features
108+
- Logging
109+
- log output format has been cleaned up
110+
- Install log and Jamf Pro log (when available) can now be viewed in the Log window (#78)
111+
- now also logs to macOS unified logging
112+
- new top-level default key to control action output logging
113+
- Network Monitoring
114+
- changes to network interfaces are now logged, see the Notes section for details (#15)
115+
- network status can be shown in the top-right corner of the Setup Manager window
116+
- new flag file `/private/var/db/.JamfSetupStarted`, which is created when Setup Manager starts
117+
- added [a specific webhook to send a message to Slack](Docs/WebHooks.md#Slack) (#104)
118+
- two new defaults keys `finishedScript` and `finishedTrigger` allow to run custom behavior when Setup Manager has finished
119+
- new option `none` for `finalAction` (#115)
120+
121+
### Fixes and Improvements
122+
- Jamf Pro: improved monitoring for Jamf Pro to complete its setup after enrollment
123+
- webhook log entries correctly show status
124+
- added `-skipAppUpdates` option to list of options for Jamf Pro policy actions
125+
- Jamf Pro policy will trigger 'Recurring Check-in' policies on empty string value
126+
127+
### Deprecations and Removals
128+
- (1.3) the minimum macOS requirement for Setup Manager is now macOS 13.5
129+
- (1.2) `showBothButtons` option removed and non-functional, there will always be just one final action button displayed
130+
- 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)
131+
132+
## v1.2.2
133+
(2025-04-17)
134+
- signed a helper script that could lead to unexpected background item prompts
135+
- disabled command-W keystroke
136+
- fixed a stall in `waitForUserEntry` with Jamf School
137+
- fixed link to computer record in Teams message (#110)
138+
- minor documentation fixes
139+
140+
## v1.2.1
141+
(2025-04-02)
142+
143+
- updated included Installomator script to [v10.8](https://github.com/Installomator/Installomator/releases/tag/v10.8)
144+
- 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
145+
- improved monitoring of Jamf Pro enrollment process and completion during the "Getting Ready" phase
146+
- minor documentation fixes (#106)
147+
148+
3149
## v1.2.2
4150
(2025-04-17)
5151
- signed a helper script that could lead to unexpected background item prompts

‎ConfigurationProfile.md‎

Lines changed: 122 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ The project some sample files to get you started:
55
- [sample plist](Examples/sample-waitForUserEntry.plist) for Jamf Pro with [two phase workflow](Docs/JamfPro-TwoPhase.md)
66
- [configuration profile](Examples/sample-jamfschool.mobileconfig) for Jamf School
77

8+
**Important:** all keys and values are **case-senstive**.
89

910
## Top-level keys
1011

@@ -74,6 +75,20 @@ Example:
7475

7576
`Please be patient.` will be bold. More detail on [Markdown here](#markdown).
7677

78+
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.
79+
80+
Use actual line breaks in the XML for line breaks in this text. (`\n` escape sequence will _not_ work in XML)
81+
82+
Example:
83+
84+
```xml
85+
<key>message</key>
86+
<string>Please be patient…
87+
88+
This line of text will be truncated when the action icon list is shown.</string>
89+
```
90+
91+
7792
#### `background`
7893

7994
(String, optional, localized, dark mode)
@@ -84,11 +99,9 @@ When this key is set, Setup Manager treats it as an image/[icon source](#icon-so
8499

85100
(String, optional, default: `enrollment`)
86101

87-
**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.
102+
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.
88103

89-
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.
90-
91-
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.
104+
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.
92105

93106
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).
94107

@@ -170,13 +183,16 @@ Disable the countdown:
170183

171184
This key sets the action and label for the button shown when Setup Manger has completed.
172185

173-
There are three options:
186+
There are four options:
174187
- `continue`: (default) merely quits Setup Manager and allows the user to continue (probably Setup Assistant or login window)
175188
- `restart`: restarts the Mac
176189
- `shutdown`: (no space!) shuts down the Mac
190+
- `none`: no button shown. (see note below)
177191

178192
**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.
179193

194+
**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.
195+
180196
This is also the action that is performed when the `finalCountdown` timer runs out.
181197

182198
When the `DEBUG` preference is set, `shutdown` or `restart` will merely quit/continue.
@@ -188,11 +204,48 @@ Example:
188204
<string>shutdown</string>
189205
```
190206

207+
#### `finishedScript`
208+
209+
(String, optional)
210+
211+
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.
212+
213+
The script has to fulfill these criteria to be executed:
214+
215+
- owner: `root`, group: `wheel`
216+
- executable bit set
217+
- not writable for group or other (file mode `755` or `555`)
218+
- no quarantine flag attached
219+
220+
The output of the finished script and trigger will be logged to `/private/var/log/setupManagerFinished.log`.
221+
222+
Example:
223+
224+
```xml
225+
<key>finishedScript</key>
226+
<string>/Library/Management/finishedScript.sh</string>
227+
```
228+
229+
#### `finishedTrigger`
230+
231+
(String, optional, Jamf Pro only)
232+
233+
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.
234+
235+
The output of the finished script and trigger will be logged to `/private/var/log/setupManagerFinished.log`.
236+
237+
Example:
238+
239+
```xml
240+
<key>finishedTrigger</key>
241+
<string>setup_manager_finished</string>
242+
```
243+
191244
#### `totalDownloadBytes`
192245

193-
(Integer, opitonal, default: 1000000000 or 1GB, v0.8)
246+
(Integer, optional, default: 1000000000 or 1GB, v0.8)
194247

195-
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.
248+
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.
196249

197250
Example:
198251

@@ -291,6 +344,26 @@ Example:
291344

292345
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.
293346

347+
#### `actionOutputLogging`
348+
349+
(string, optional, default: `error`)
350+
351+
This key controls whether the output of actions is written to the Setup Manager log file.
352+
353+
There are three options:
354+
- `always`: output and exit code are always written to the log file
355+
- `error`: (default) output and exit code are only written on errors
356+
- `never`: output and exit are never written to the log file
357+
358+
Setup Manager's log window will always show the output, regardless of this setting.
359+
360+
Example:
361+
362+
```xml
363+
<key>actionOutputLogging</key>
364+
<string>always</string>
365+
```
366+
294367
## Actions
295368

296369
All actions should have these keys:
@@ -358,7 +431,7 @@ Example:
358431
This will run the Jamf Pro policy or polices with the given trigger name. This is the equivalent of running
359432

360433
```
361-
jamf policy -event <triggername> -verbose -forceNoRecon -doNotRestart -noInteraction
434+
jamf policy -event <triggername> -verbose -forceNoRecon -doNotRestart -noInteraction -skipAppUpdates
362435
```
363436

364437
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 +449,20 @@ Example:
376449
</dict>
377450
```
378451

452+
Note: You can trigger policies attached to "Recurring Check-in" by leaving the string value empty:
453+
454+
455+
```xml
456+
<dict>
457+
<key>icon</key>
458+
<string>symbol:arrow.trianglehead.2.clockwise.rotate.90</string>
459+
<key>label</key>
460+
<string>Check-in</string>
461+
<key>policy</key>
462+
<string/>
463+
</dict>
464+
```
465+
379466
### Watch Path
380467

381468
#### `watchPath`
@@ -476,9 +563,9 @@ Example:
476563

477564
### Installomator
478565

479-
This will run [Installomator](https://github.com/Installomator/Installomator) to install a given label.
566+
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.
480567

481-
Note: by default, Setup manager will add `NOTIFY=silent` to the arguments to suppress notifications. You can override this in the `arguments`.
568+
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.
482569

483570
#### `installomator`
484571

@@ -505,6 +592,21 @@ Example:
505592
</dict>
506593
```
507594

595+
with arguments:
596+
597+
```xml
598+
<dict>
599+
<key>label</key>
600+
<string>Example App</string>
601+
<key>installomator</key>
602+
<string>example</string>
603+
<key>arguments</key>
604+
<array>
605+
<string>downloadURL=https://example.com/alternativeURL</string>
606+
</array>
607+
</dict>
608+
```
609+
508610

509611
## Icon Sources
510612

@@ -824,6 +926,10 @@ Example:
824926

825927
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).
826928

929+
## Network Connectivity
930+
931+
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).
932+
827933
## Localization
828934

829935
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,6 +992,10 @@ The following keys can be localized:
886992
- `message`
887993
- `url`
888994

995+
### Network Check
996+
997+
- `label`
998+
889999
Use these two-letter codes for these languages:
8901000

8911001
| Language | two-letter code |
@@ -894,9 +1004,10 @@ Use these two-letter codes for these languages:
8941004
| Dutch (Nederlands) | nl |
8951005
| French | fr |
8961006
| German | de |
897-
| Italian | it |
8981007
| Hebrew | he |
1008+
| Italian | it |
8991009
| Norwegian | nb |
1010+
| Polish | pl |
9001011
| Spanish | es |
9011012
| Swedish | sv |
9021013

0 commit comments

Comments
 (0)