Mac Admin

Migrating macOS Devices from one Jamf Pro instance to another using ReEnroller – Part 1: Setup

So over the last few weeks I’ve seen a few questions pop up around the usage of the Jamf ReEnroller solution, and using it to migrate macOS devices from one Jamf Pro instance to another. It just so happens I’ve had to do this for a few customers to onboard them into datajar.mobi, so I thought I’d share what I’ve learnt!

I’m planning on a two post mini-series with this part 1 covering some background information as well as suggested setup details. Part 2 will look to cover the process and some troubleshooting tips.

What is ReEnroller?

ReEnroller is a tool created by the folks at Jamf. It produces an installer package that deploys an application and settings to migrate a macOS device from one Jamf Pro system to a second one. Ideal if moving providers or changing the Jamf Management URL.

Using an API script, it can also remove an MDM Profile that is set to be “Unremovable” via a ADE (previously DEP) enrolment.

Limitations

Don’t forget that the system you’re using to migrate is also running the migration, so this can be fragile. Also Apple doesn’t provide a supported way to migrate MDM solutions other than a full wipe and redeploy. It is fairly likely you’ll have a few devices (maybe more) which fail to migrate at all and will need a manual intervention, possibly even including a wipe to bring them back into service.

Also this won’t provide a User Approved MDM (UAMDM) enrolment, so your users will need to manually hit that “Approve” button post-migration. As a result, you’ll want to not block access to the “Profiles” System Preference Pane.

Lastly, in my experience, you need to have the destination Jamf Pro instance running the same or newer Jamf Pro version to minimise the risk of failed migrations.

Oh and depending how things end up, this process might not work on macOS Big Sur. More on this in part 2.

Where do I find more information or documentation?

Jamf have some documentation on the use of ReEnroller on the GitHub README file, but this doesn’t provide detailed implementation instructions. It does mention this line: Be sure to view the help for detailed usage instructions.

To view the implementation instructions, grab a copy of the application from the releases page, launch it and click the “?” next to the “Build” button. This will provide some detailed documentation on usage and implementation of ReEnroller.

Oh and also this blog series might help 😉

Setup work

For this walkthrough, I’ll be using the term “source” to mean the current or old Jamf Pro instance the device is currently enrolled in, and “destination” to mean the new Jamf Pro instance.

So in order to setup the Jamf ReEnroller we’ll need to:

  • Create a Jamf API account in the destination instance (and a second one in the source instance if you need to remove an ‘unremovable’ MDM profile)
  • Add the script to run an API command to remove an ‘unremovable’ MDM profile, if required
  • Create and upload the ReEnroller installer package into the source Jamf Pro instance
  • Create a policy in the source Jamf Pro instance to run the ReEnroller installer package (and possibly a second one for the MDM removal script, if required)
  • Create a policy in the destination Jamf Pro instance to run a one line command to confirm the migration is successful

Lets walk through each step in more detail

Create the Jamf Pro API enrolment account on the destination Jamf Pro instance

So first things first, we need to create an API enrolment account on the destination Jamf Pro instance. This will be used by the App to create an invitation enrolment and perform the enrolment.

  1. Log into your destination Jamf Pro server and create a new account. I’d suggest the username “ReEnrollerAPIEnrolment” to make things simple.
  2. Give it a long and complex password and set the privilege set to “Enrollment Only”.

(Optional) Create the Jamf Pro API MDM removal account on the source Jamf Pro instance

If you’ve enrolled macOS devices into your source server with DEP and a non-removable MDM Profile (option shown below), you’ll need to setup an account on the source Jamf Pro instance in order to remove the profile.

  1. Log into your source Jamf Pro server and create a new account. I’d suggest the username “ReEnrollerAPIMDMRemoval” to make things simple.
  2. Give it a long and complex password, set the privilege set to “Custom” and give it the following permissions only:
  • Jamf Pro Server Objects > Computers > Allow Create and Read
  • Jamf Pro Server Actions > Send Computer Unmanage Command > Allow

(Optional) Add the Jamf Pro API script to remove the MDM profile in the source Jamf Pro instance

Again, if you need to use the API to remove the MDM profile to migrate devices, we’ll need to add a script to the source Jamf Pro instance.

  1. Log into your source Jamf Pro server and create a new script. I’d suggest sticking with the default name of apiMDM_remove.
  2. For the content of the script, use the contents of this file from the GitHub repo. This should ensure that you’re using the most up to date version.
  3. Set the parameter names to the below:
  • Parameter 4 – Username
  • Parameter 5 – Password
  • Parameter 6 – Server

(Optional) Add the Jamf Pro policy to remove the MDM profile in the source Jamf Pro instance

Again-again, if you need to use the API to remove the MDM profile to migrate devices, we’ll need to add a policy to the source Jamf Pro instance.

  1. Log into your source Jamf Pro server and create a new policy. I’d suggest calling it something obvious like “API MDM Removal”.
  2. Set the Execution Frequency to “Ongoing” and the Trigger to “Custom”. In the Custom Event box, enter apiMDM_remove.
  3. Add the API script we added above (default name of apiMDM_remove)
  4. In the Username and Password parameter boxes, enter the details of the API MDM removal account we created above (suggested username of ReEnrollerAPIMDMRemoval)
  5. In the server parameter box, enter the source Jamf Pro instance address
  6. Under the Scope tab, configure “All Computers” as the target
  7. Save the policy

Create the Jamf Pro policy to confirm the migration in the destination Jamf Pro instance

We now need to create a ‘completed’ policy in the destination Jamf Pro server. The ReEnroller workflow will trigger this policy to confirm the migration has been successful.

  1. Log into your destination Jamf Pro server and create a new policy. I’d suggest calling it something obvious like “Migration Confirmation”.
  2. Set the Execution Frequency to “Ongoing” and the Trigger to “Custom”. In the Custom Event box, enter jpsmigrationcheck.
  3. Add the Files and Processes payload
  4. In the Execute Command box, enter the following (all on one line)
    1. touch /Library/Application\ Support/JAMF/ReEnroller/Complete
  5. Under the Scope tab, configure “All Computers” as the target
  6. Save the policy

Create the ReEnroller installer package with the required settings

Now we have some decisions to make. We need to use the ReEnroller Application to generate a package that will do the actual work. Below I’ll cover each option and offer my opinion on what to use. Feel free to experiment as long as you do plenty of testing afterwards!

First things first, download the latest copy of ReEnroller from the GitHub releases. Once obtained, launch the application.

Lets go through each box and option:

  • New Jamf Server URL – Set this to the destination Jamf Pro instance’s URL
  • Username – Set this to the username of the API Enrolment account (suggest name of ReEnrollerAPIEnrolment)
  • Password – Set this to the matching password of this account

  • Management Account – Enter the desired Management Account. If you already have a management account on the device, I’d suggest using those details unless you have a specific need to use something else.
  • Password / Verify Password – Enter the desired Management Account password. Again, if you already have a management account on the device, I’d suggest using those details unless you have a specific need to use something else.
    • Randomly Generate Password – Alternatively, you can use a randomly generated password and specify the number of characters.
      • Note: If you do go for the random password you’ll need to add a “Reset Management Account Password” payload to the migration complete policy in the destination server
  • Create the account if it does not exist – Tick to create the Management Account automatically. I’d suggest having this ticked
  • Hide the account – Hide the Management Account from the GUI. Set this to what you need
  • Configuration Profile – If you’re deploying a Wifi profile via MDM, you’ll need to upload a copy of the profile here. This will ensure the device stays connected to a network during the entire migration process.
    • Remove when done – If using a profile for Wifi, tick this to remove that profile after ReEnroller is done
  • Use for new enrollment – If you tick this, the outputted package will not work for migrations! Do not tick this if you’re using this solution to migrate devices
  • Remove profiles marked in DEP as not to be removed – If these devices are pre macOS 10.13, this will remove the MDM profile (needed if you’re migrating to a new server). If the device has a DEP non-removable MDM profile, it’ll use the policy we created above (recommended name “API MDM Removal”) to unenrol and remove the profile. I’d suggest ticking this.
  • Use existing site membership – Tick if you’re using Sites in Jamf and want the devices to try and enrol into the same Site on the destination instance
  • Enroll in site [XXXX] – Use this to instead specify a Site you want these device to enrol into
  • Skip MDM Verification – If you aren’t using APNs on the destination (for some reason?) you can skip this test. I’d suggest leaving this unticked
  • Create ‘Migration Complete’ policy on the new Jamf Server – You can leave this unticked as we’ve done this ourselves. This means we can use an enrolment only account with ReEnroller – much better security!
  • Run policy after verifying migration. Policy ID [XX] – If you have a specific policy you need to run on the destination server after migration, enter the policy ID number here. This could be a progress screen or some initial setup items you need on all Macs.
  • Call Automated Device Enrolment – When enabled, this can trigger an ADE / DEP prompt enrolment to the user. It’ll still require the user to perform a number of tasks so I prefer to not use this
  • Remove ReEnroller folder after migration – When ticked, it’ll clean up any leftovers! Handy to have unticked for testing but I’d strongly suggest ticking this option to make sure nothing sensitive is left behind.

  • Maximum number of retries [XX] – ReEnroller will retry automatically if it finds any issues (more on this in part 2). I’d suggest leaving this blank to have ReEnroller keep retrying until its successful.
  • Retry interval – ReEnroller will retry after 30 minutes by default. This is a pretty good default setting I’d suggest leaving as-is, but feel free to change if you need to.
  • Create Separate Packages – If ticked, this will create a separate package for the Launch Daemon and the migration tools. I’d personally not bother!
  1. Your ReEnroller application should look something like the above.
  2. Click the Build button to produce your ReEnroller package.
  3. Upload this to your source Jamf Pro Server

Create the Jamf Pro policy to run the ReEnroller installer package in the source Jamf Pro instance

Almost there! We now need to create a policy on the source Jamf Pro instance to run the ReEnroller package. This will be a fair bit of personal choice but generally speaking I’d suggest:

  • Obviously add the ReEnroller Package to the policy!
  • Set the frequency to “Ongoing”, the scope to “All Computers” (after testing) and put it in Self Service only
  • Give it a nice logo and a good description
  • Consider informing the user of the whole process in the description and require that they view it before running the policy
  • As a last ditch, you can switch it to a “recurring check in” trigger to get those last few devices over the line.

Test!

And lastly, test. Test, test, test and test some more. Then test again for good luck. the process can be fragile in the best of cases but you can at least test it enough to be confident of the best possible outcome.

Outro

Phew that was a long one. In part 2 I’ll look to cover the process, and any troubleshooting advise I can provide.

As always, if you have any questions, queries or comments, let me know below (or @daz_wallace on Mac Admins Slack) and I’ll try to respond to and delve into as many as I can.

Standard

One thought on “Migrating macOS Devices from one Jamf Pro instance to another using ReEnroller – Part 1: Setup

  1. Pingback: Migrating macOS Devices from one Jamf Pro instance to another using ReEnroller – Part 2: Process and Troubleshooting | dazwallace

Comments are closed.