jamf/Setup-Manager
1
0
Fork 0
mirror of https://github.com/jamf/Setup-Manager.git synced 2026-02-03 14:13:24 +00:00
Code Issues 37 Actions Packages Projects Releases Wiki Activity

updated docs for 1.1beta

Browse Source
This commit is contained in:
Armin Briegel
2024-09-09 15:55:00 +02:00
parent 4aabab6033
commit 0e4961a42a
13 changed files with 694 additions and 290 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
Docs/Extras.md Normal file
View File

@@ -0,0 +1,80 @@
# Extras and Notes
## Custom JSON Schema for Jamf Pro
- create a new profile
- go to ‘Application & Custom Settings’
- select ‘Jamf Applications’
- click the ‘+ Add’ button
- in the ‘Jamf Application Domain’ popup select ‘com.jamf.setupmanager’
- for the version select the version of Setup Manager you are using
- for the ‘Variant’, select ‘Setup Manager.json’
- fill in your 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.
## Quit
The command-Q keyboard short cut to quit the app is disabled. You can use shift-control-command-E instead. This should only be used when debugging as it may leave the client in an undetermined state when installations are aborted.
## Logging
Setup Manager logs to `/Library/Logs/Setup Manager.log`. While Setup Manager is running you can open a log window with command-L.
## Debug mode
When you set the `DEBUG` key to `true` in the profile or locally with the `defaults` command Setup Manager will not perform any tasks that actually perform installations or otherwise change the system.
You will also be able launch the app as the user, by double-clicking the app in `/Applications/Utilities`. This is useful to test the look and feel of your custom icons, text and localization. When you use this to create screen shots for documentation, also note the `overrideSerialNumber` and `hideDebugLabel` keys.
## Flag file
Setup Manager creates a flag file at `/private/var/db/.JamfSetupEnrollmentDone` when it finishes. If this file exists when Setup Manager launches, the app will terminate immediately and without taking any action. You can use this flag file in an extension attribute in Jamf to determine whether the enrollment steps were performed. (Setup Manager does not care if the actions were performed successfully.)
When `DEBUG` is set to `true` in the defaults/configuration profile, the flag file is ignored at launch, but may still be created when done.
In Jamf Pro, you can 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
```
And then create a Smart Group named "Setup Manager Done" with the criteria `"Setup Manager Done" is "done"`. This can be very useful for scoping and limitations.
## User Data file
The data from user entry is written to a file when Setup Manager reaches a `waitForUserEntry` step and again when it finishes. The file is stored at `/private/var/db/SetupManagerUserData.txt`. When `DEBUG` is enabled, the file will be written to `/Users/Shared/`.
The file is plain text with the following format:
```
start: 2024-08-14T13:52:56Z
userID: a.b@example.com
department: Sales
building: Example
room: ABC123
assetTag: XYZ888
computerName: MacBook-M7WGMK
submit: 2024-08-14T13:54:37Z
duration: 101
```
Start time (`start`) and finish/submission time (`submit`) are given in ISO8601 format, universal time (UTC).
Fields that were not set in user entry will not be shown at all. You can use this file in scripts or extension attributes. The easiest way would be to parse it with `awk`, e.g.
```
duration=$(awk -F ': ' '/duration: / {print $2}' /private/var/db/SetupManagerUserData.txt)
```
## Final action and shutdown
When the app is not running as root (for testing or from Xcode) or when the `DEBUG` preference is set, shutdown will merely quit.
## "About This Mac…" window
When you hold the option key when clicking on "About This Mac…" you will see more information.

35
Docs/FAQ.md Normal file
View File

@@ -0,0 +1,35 @@
# Frequently Asked Questions
## Is there are custom JSON Schema for Jamf Pro?
[Yes.](Extras.md#custom-json-schema-for-jamf-pro)
## Can you block the user desktop with user initiated enrollment?
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
There can be many causes for this. 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.
## Does Setup Manager require Jamf Connect
No.
Setup Manager will run fine without Jamf Connect. You can even build 'single-touch' style workflows with Setup Manager withough Jamf Connect. Some features, such as pre-assigning a device to a specific user require Jamf Connect, though.
## How can I use the icon for an app before the app is installed?
- 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
## What is happening during the "Getting Ready" steps?
During the "Getting Ready" phase, Setup Manager is waiting for the Jamf Pro configuration to be complete, and runs a recon, so that policies during the enrollment phase can already be scoped. You cannot change the steps in this phase. You can see the details and possibly failures in the Setup Manager log.

71
Docs/JamfPro-QuickStart.md Normal file
View File

@@ -0,0 +1,71 @@
# Jamf Pro: Setup Manager Quick Start
## Upload Setup Manager package
Download the latest version of the Setup Manager installation pkg from the [releases page](https://github.com/Jamf-Concepts/Setup-Manager/releases/latest).
In the Jamf Pro web interface, go to Settings > Packages. Create a new package and upload the Setup Manager installer pkg file to Jamf Pro. Save the package.
_Note:_ when the package is marked as 'pending' it will not work in prestage deployment. Wait with testing deployments until the 'pending' flag has disappeared.
## Prepare a Jamf Pro policy for use with Setup Manager
Setup Manager can trigger policies in Jamf Pro. By triggering a sequence of Jamf Pro policies all the required software and configurations will be installed on the device.
## Create the Setup Manager configuration profile
- Go to Computers > create a new profile
- Name the profile 'Setup Manager'
- assign a category, ensure the Level is set to 'Computer Level'
- in payload sidebar select 'Application & Custom Settings', then select 'Jamf Applications'
- click the '+ Add' button
- for the 'Jamf Application Domain' choose `com.jamf.setupmanager`
- for the version select the version of Setup Manager you are using
- for the 'Variant', select `Setup Manager.json`
### Profile values
- for the Icon Source, enter `name:NSComputer`. This is a special value that tells Setup Manager to use an image of the computer it is running on. There are many other options you can use as an icon source [documented here](../ConfigurationProfile.md#icon-source).
- for the Title, enter `Welcome to Setup Manager!`
- for the Message, enter `Please be patient while we set up your new Mac…`
### Enrollment
- under Enrollment Actions, click on 'Add Item'
- for item 1, from the 'Select Action Type' popup, choose "Installomator"
- for 'Action Label,' enter `Google Chrome`
- for 'Action Icon Source,' enter `symbol:network`
- for 'Installomator Label' enter `googlechromepkg`
- click 'Add Item'
- for item 2, from the 'Select Action Type' popup, choose "Shell Command"
- under 'Command Arguments', click 'Add argument', enter `-setTimeZone`
- click 'Add argument' again and enter your time zone in the format `Europe/Amsterdam` (the 'TZ identifier' [from this list](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones))
- for 'Action Label,' enter `Set Time Zone`
- for 'Action Icon Source,' enter `symbol:clock`
- for 'Requires Root' select `true`
- for 'Shell Command Path' enter `/usr/sbin/systemsetup`
You can add more actions here. There are more types of actions available, you can use a 'Jamf Policy Trigger' action to run a policy with a custom trigger. You can also use a 'Watch Path' action to wait for an app to be installed from the Mac App Store or Jamf App Installers.
## Scoping and Prestage
- 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 option _disabled_ (so that _is_ displayed)
- ensure your test Mac(s) is (are) assigned to the Prestage
## Wipe the Test Mac
- on the test mac, choose 'Erase all Contents and Settings' in the Settings app or wipe the Mac using the 'Wipe Computer' remote management command in Jamf Pro
- click through the initial enrollment dialogs. After you approve the enrollment in your MDM, Setup Manger should appear and perform the actions you configured
- while the installations are progressing, click on "About this Mac…" for information, click again while holding down the option key for even more information
- hit command-L for a log window. You can also find this log info later at `/Library/Logs/Setup Manager.log`
## Next Steps
- add more actions to Setup Manager, you can use more Jamf Pro policies, Installomator labels, or shell actions
- add a computer name template key to the profile to automate computer naming
- add a `help` section 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 section in the profile

60
Docs/JamfPro-TwoPhase.md Normal file
View File

@@ -0,0 +1,60 @@
# Jamf Pro: extra installations based on user data entry
In this simple example workflow, we run certain Jamf Pro policies depending on the department. This example can be expanded to other user entry data fields.
- create Setup Manager configuration profile
- create a `userEntry` key with a list of options for the department:
```xml
<key>userEntry</key>
<dict>
<key>department</key>
<dict>
<key>options</key>
<array>
<string>Sales</string>
<string>Development</string>
<string>IT</string>
<string>Marketing</string>
</array>
</dict>
</dict>
```
Note that you need to have the matching departments in Jamf Pro.
- add the `enrollmentActions` that should run on all computers first
- then add a `waitForUserEntry` action:
```xml
<dict>
<key>label</key>
<string>Submit entries</string>
<key>waitForUserEntry</key>
<string/>
</dict>
```
When Setup Manager reaches this action it will wait for the user data entry to be complete if it isn't already. Then Setup Manager will submit the data from the user entry to Jamf Pro and run a recon, so you can use the data for scoping subsequent policies.
Setup Manager also saves the data from user entry in a plain text file which you can use in policy scripts after the `waitForUserEntry` action. [See details here.](Extras.md#user-data-file)
- Insert this action
``` xml
<dict>
<key>icon</key>
<string>symbol:plus.app</string>
<key>label</key>
<string>Extra Apps for %department%</string>
</dict>
<key>policy</key>
<string>install_extra_apps</string>
</dict>
```
- for the policies you want run/install depending on the user entry:
- give the policy a custom trigger matching the trigger in 'Extra Apps' action: `install_extra_apps`
- scope the policy to the department(s) that should receive the installations
- repeat for every extra installation that depends on the user entry

106
Docs/JamfProConnect-SingleTouch.md Normal file
View File

@@ -0,0 +1,106 @@
# Single Touch workflow with Jamf Pro and Jamf Connect
## What is Single Touch?
In a single touch workflow a tech performs or monitors the initial setup of a device to the point just before the user creates their account. While Setup Manager can run zero-touch workflows, it was built specifically with single-touch workflows in mind.
A single touch workflow can be as easy the tech unpacking the Mac (erasing it with an MDM command or restoring it with Apple Configurator when necessary), connecting it to network, stepping through the initial Setup dialogs, optionally entering the asset tag or other data, monitoring Setup Manager's process until it is finished and then handing over or sending the Mac to the designated end user who continues the setup and creates their account in Setup Assistant.
You can use a combination of Jamf Pro, Setup Manager and Jamf Connector, to get a tighter deployment, user assignment and account creation process. This requires a bit more setup and configuration. This workflow allows the tech to monitor the Setup Manager workflow, enter device specific data such as an asset tag and assign _and lock_ the device to a different user, without requiring the end user's login credentials.
## What you need
- Jamf Pro
- Setup Manager
- Jamf Connect Login configured with SSO
Customized Enrollment with SSO is not _required_ for this workflow. The assignment to the final user is set from the email entered in Setup Manager. Nevertheless, customized enrollment with SSO is useful in this context since restricts Mac enrollment to a group of authorized accounts.
You should have Jamf Pro and Jamf Connect configured with the required SSO integrations and thoroughly tested before configuring this workflow.
## Configure Setup Manager
Add the Setup Manager pkg to the Prestage. Also create a configuration profile for Setup Manager with the workflow to install and configure the software you want to be installed at this stage.
You need to leave least one panel of Setup Assistant _enabled_. Otherwise Setup Manager might not launch.
Setup Manager profile will require a `userEntry` field for `userID` to know which user to assign the Mac to. This will show a field prompting for "User Email." You can of course add other fields to `userEntry` at this time, though they are not required.
Example:
```xml
<key>userID</key>
<dict>
<key>placeholder</key>
<string>first.last@example.com</string>
<key>validation</key>
<string>\S+\.\S+\@example\.com</string>
<key>validationMessage</key>
<string>Email needs to be for example.com!</string>
<key>validationMessage.de</key>
<string>Email muss für example.com sein!</string>
</dict>
```
## Deploy Jamf Connect
You also need to make sure that Jamf Connect (Login) is deployed is installed and configured. There are different approaches to do this.
- add Jamf Connect pkg to prestage
- install Jamf Connect with a pkg policy triggered from Setup Manager workflow
- install Jamf Connect with Installomator action in Setup Manager workflow
- install Jamf Connect with Jamf App Installers
When you upload the Jamf Connect pkg to Jamf Pro and add it to either the Prestage or a policy, you retain control over which version of Jamf Connect gets deployed. With Installomator or Jamf App Installer you will always get the latest available version.
When you use Jamf App Installers you have no direct control over when the installation actually occurs. You should add a `watchPath` action at the end of your `enrollmentActions` array in the Setup Manager profile to ensure that Jamf Connect is installed before proceeding:
```xml
<dict>
<key>label</key>
<string>Jamf Connect</string>
<key>icon</key>
<string>symbol:app.badge</string>
<key>watchPath</key>
<string>/Applications/Jamf Connect.app</string>
<key>wait</key>
<integer>900</integer>
</dict>
```
## Create Extension Attribute
The email entered for userID will be submitted to Jamf Pro at the end of the Setup Manager workflow. When the Setup Manager workflow is done a flag file will be created at `/private/var/db/.JamfSetupEnrollmentDone`. We can use this to scope profiles and policies to Macs that have finished the Setup Manager workflow.
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"`.
## Pre-set user for Jamf Connect
Jamf Connect Login allows pre-configuring the user. Create a configuration profile named "Jamf Connect Enrollment User" to the preference domain `com.jamf.connect.login` with the following property list:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>EnrollmentRealName</key>
<string>$REALNAME</string>
<key>EnrollmentUserName</key>
<string>$EMAIL</string>
</dict>
</plist>
```
Scope this configuration profile the "Setup Manager Done" smart group you created earlier.
With this setup, the configuration profile that presets the user in Jamf Connect Login will be pushed out after Setup Manager finishes its final recon, which sets the user information to the Mac in Jamf Pro.

166
Docs/JamfSchool-Setup.md Normal file
View File

@@ -0,0 +1,166 @@
# Installation and Configuration: Jamf School
## Selecting Deployment Method
Jamf Setup Manager can be deployed to run at two different points during a device deployment. Right after enrollment (the default) and at login window. You must select which method is appropriate for your deployment before configuring the Jamf Setup Manager Workflow in Jamf School
### At Enrollment (Default)
Jamf Setup Managers default deployment action is to run at `Setup Assistant`.
Setup Manager will appear and during `Setup Assistant` allowing the user to continue to configure `Setup Assistant` after Setup Manager has completed its tasks.
_**This method is recomended for 1:1 environments**_
Example
> You deploy 1:1 MacBooks, want to ensure that critical software installed prior to the user working on the device but also require the user to configure TouchID and create a user account during the onboarding.
> The user will connect the MacBook to the network and enroll into MDM. After a short delay Setup Manger will run and complete its tasks and install critical software
> Once complete the user will be released back to Setup Assistant where they will be able to use the Setup Assistant panes to configure TouchID and create a user
With this default method you will require an Automated Device Enrollment Profile configured with
- At least one setup assistant pane configured
- *“Wait for the configuration to be applied before continuing the Setup Assistant”* box checked
- An admin account should be configured as required
- Other ADE profile setting should be set as required
- _**Do Not**_ select `Auto Advance`
> If the user skips through all of the Setup Assistant panes before Setup Manager launches or Auto Advance is selected. and the device lands on the login screen, Setup Manager will not launch
### At Login Window
Jamf Setup Manager can be configured to run at `Login Window`.
Setup Manager will appear once the device has ran through `Setup Assistant` and is waiting at the login screen and run through its tasks. Releasing back to the login window once complete.
_**This method is recommended for lab environment**_
Example
> You are deploying a lab of iMacs ready for the new academic year. You wish to connect iMacs to the network with ethernet, power on and leave the devices to enroll and build while you complete other tasks.
> After configuring an ADE profile with Auto Advance an iMac will enroll into Jamf School and move through Setup Assistant without any user interaction. Once at the login Window Setup Manager will run and complete its tasks.
> Once Setup Manager is complete the build is complete
To run Setup Manager at `Login Window` you will require
1. A Setup Manager Profile with the key `runAt` and `String Value` of `loginwindow`
2. An Automated Device Enrollment Profile configured with
- An admin account
- `Auto Advance` configured
- Other ADE profile setting should be set as required
---
## Jamf Setup Manager Workflow Requirements
In order to configure the workflow in Jamf School you will need
- A Jamf Setup Manager Configuration Profile (customized for your deployment, example profile below) uploaded to Jamf School
- Jamf Setup Manager package installer (available from Jamf Concepts) uploaded to Jamf School
- An Automated Device Enrollment Profile with the correct settings for your chosen deployment method (`default` or `LoginWindow`)
---
**Step 1: Configuration Profile**
Create a Payload-less Profile for Smart Group Targeting
- Navigate to profiles and create a new macOS Profile
- Name it *“Jamf Setup Manager Installed”*
- Do not scope the profile and do not configure any payloads. Simply save the profile
---
**Step 2: Smart Group for Setup Manger Config Profile**
Create a Smart Group to target your required Macs
- Navigate to `Devices → Device Groups` and create a new group. Ensure you select `Smart Group`
- Name the Group *“Jamf Setup Manager Profile”* skip all other panes until members
- In members select `Automated Device Enrollment Profile` `equals` and then select the ADE profile that you created as part of the requirements step. This will target any and all devices that enrol using that ADE profile
> If you only want to select a subset of macOS devices, for example Lab Mac devices and not 1:1 devices, configure this group to target additional critera the desired devices in your environment will have
- `Save` Scope
- Next in the `Profiles` tab add the Jamf Setup Manager Configuration Profile that you uploaded to Jamf School
---
**Step 3: Smart Group to install Setup Manager**
Create a Smart Group to target devices with Jamf Setup Manager Profile Installed to deploy the Setup Manager pkg
- Navigate to `Devices` → `Device Groups` and create a new group. Ensure you select `Smart Group`
- Name the Group *“Install Jamf Setup Manager”*, skip all other panes until members
- In members select `Managed Profile (Installed)` `equals` and then select the Jamf Setup Manager Configuration Profile that you uploaded to Jamf School
- `Save` Scope
- Next in the `Apps` tab add the Jamf Setup Manager pkg and in the `Profiles` tab select the *“Jamf Setup Manager Installed”* profile you created in Step 1
> If you named your profile in step 1 something different, be sure to select that profile in this step
---
**Step 4: Smart Group for all other apps and configurations**
Create a Smart Group to target devices with the “Jamf Setup Manager Installed” profile installed and deploy the rest of the profile and apps
- Navigate to `Devices` → `Device Groups` and create a new group. Ensure you select `Smart Group`
- Name the group *“macOS Management & Apps”*, skip all other panes until members
In members select `Managed Profile (Installed)` `equals` and then select *"Jamf Setup Manager Installed"* profile that you created in Step 1
> If you named your profile in step 1 something different, be sure to select that profile in this step
- Next in the `Apps` tab add any apps or packages that will not be installed via Installomator as part of the Jamf Setup Workflow and in the `Profiles` tab any any and all config needed to manage your Macs
- If you install packages or App Store apps through Jamf School, and you want to report on them as part of the Jamf Setup Manager workflow be sure to add `Watchpaths` for the apps / content into the Jamf `Setup Manager Configuration Profile` before uploading to Jamf School
---
### Workflow
These chained amart group actions then perform the following flow
- Scope the Jamf Setup Manager Config profiles to all macOS devices enrolled with a given ADE profile
- Once the Profile is reported as installed by Jamf School, it will then install the Jamf Setup Manager pkg (since we 100% know the config profile is on the device before the pkg, we know it’ll be configured in the correct manner) and the *“Jamf Setup Manager Installed”* profile
- Only when the device reports back that it has *“Jamf Setup Manager Installed”* profile will it move into the next smart group where it will receive the `commands` to install further apps / packages and the rest of the configuration profiles.
With this flow we are controlling, the best we can, that the first thing the device does is install Jamf Setup Manager and the required config. This is rather than having Jamf Setup Manager queued further down a list of apps that are installing.
> You can view the device activity log in the Jamf School console to ensure that the InstallEnterpriseApp command for Setup Manager is received before other app commands, for testing and troubleshooting.
---
### Workflow Considerations and Warnings
The Jamf Setup Manager workflow for Jamf School has been designed to take advantage of profile installation reporting in smart groups and in part to tackle the fact that Jamf School does not have a concept of *“Pre-Stage Packages”*. As such the workflow relies on chaining together smart groups where membership of one group is dependent on an action of the previous step.
Example
> You can view the device activity log in the Jamf School console to ensure that the InstallEnterpriseApp command for Setup Manager is received before other app commands, for testing and troubleshooting.
>
If an admin to accidentally unscoped the *“Jamf Setup Manager Installed”* profile from a device it would then fall out of scope of the *“macOS Management & Apps”* group, as its membership criteria requires the *“Jamf Setup Manager Installed”* profile to be installed on the device.
> Since the *“macOS Management & Apps”* group is where all of the management and App Store apps are scoped removal from this group means the device has the profiles and App Store apps removed, resulting in a device in an unexpected state.
Therefore it is essential that the device maintains this chained smart group flow throughout its deployment.
Should you need to `update`, `amend` or `edit` the `Jamf Setup Manager Configuration Profile` that controls Setup Manager, you will need to do this locally and then re-upload to Jamf School.
For best results we recommend the following workflow
- Navigate to the current profile in Jamf School in the `Profiles` -> `Configuration Profiles` menu
- Click the `pencil icon` to edit
- Click `replace profile`
- Drag local updated profile to the revealed box or click on the box to navigate to the profile
- Click `save`
Following this workflow keeps the name of the profile in Jamf School the same as the previous version and there is no need to edit / add a different or new profile the the scope in `Step 2` or change the criteria for the name of the installed profile in `Step 3`
Should you want to keep different versions of the Jamf Setup Manager Configuration Profile in Jamf School in order to switch between different Setup Manager actions please ensure that you update the profile in `Step 2` and `Step 3` to match the desired Jamf Setup Manager Configuration Profile prior to deploying devices. Failure to do this could result in the breaking of the smart group chain required for Jamf School resulting in devices in an unexpected state (ie not with the desired configurations and/or apps)