Network Migration

This tool moves a Mac from one 802.1x configuration profile to another without anyone having to touch the device. It swaps the Mac between the Jamf Pro static groups the two profiles are scoped to, waits for macOS to actually remove the old profile and install the new one, then joins the new network.

Because the Mac loses its network connection partway through the swap, the tool can park it on a broadcasted "guest" SSID for the duration and reconnect it afterwards — that is what --ssid and --networkpw are for.

How it works

1. Validates the two profiles and the two static groups before changing anything.
2. Joins the migration SSID, so the Mac stays reachable while its profile is replaced.
3. Adds the Mac to the removal group, which is scoped in the old profile's exclusions, and waits for that profile to disappear.
4. Adds the Mac to the target group, which is scoped in the new profile's targets, and waits for that profile to install.
5. Joins the new profile's SSID, retrying until the network is reachable.
6. Optionally forgets the migration SSID.

Note on timeouts: an SSID can take a few seconds to become visible after its profile installs, and an 802.1x certificate delivered through ADCS can take minutes to enrol. If certificate delivery is slow in your environment, raise --joinTimeout rather than assuming the migration failed.

Prerequisites

• Both 802.1x configuration profiles already exist in Jamf Pro.
• The old profile excludes a static computer group — that group's ID is --removalGroupId.
• The new profile targets a static computer group — that group's ID is --targetGroupId.

You can read any of these IDs out of the Jamf Pro URL while viewing the object, for example https://yourorg.jamfcloud.com/staticComputerGroups.html?id=233.

Command Options

rocketman NetworkMigration

Required Parameters

--ssid [string]

The broadcasted SSID the Mac uses while the migration is happening.

• Type: string
• Example:

  --ssid "Company Guest"

--networkpw [string]

Password for the network named by --ssid. Encrypt it with the Encrypt tool.

• Type: string
• Example:

  --networkpw "ENC:..."

--clientId [string]

Client ID for Jamf API authentication. Encrypt it with the Encrypt tool.

• Type: string
• Example:

  --clientId "..." OR --clientId "ENC:..."

--clientSecret [string]

Client secret for Jamf API authentication. Encrypt it with the Encrypt tool.

• Type: string
• Example:

  --clientSecret "..." OR --clientSecret "ENC:..."

--removalGroupId [integer]

ID of the static computer group scoped in the old profile's exclusions.

• Type: integer
• Example:

  --removalGroupId 233

--targetGroupId [integer]

ID of the static computer group scoped in the new profile's targets.

• Type: integer
• Example:

  --targetGroupId 108

--oldProfileId [integer]

ID of the 802.1x configuration profile being replaced.

• Type: integer
• Example:

  --oldProfileId 262

--newProfileId [integer]

ID of the 802.1x configuration profile replacing it.

• Type: integer
• Example:

  --newProfileId 17

Optional Parameters

--computerId [integer]

The Jamf computer ID being migrated. When omitted, the tool looks the Mac up by its serial number.

• Type: integer
• Example:

  --computerId 103

--newNetworkPw [string]

Password for the new profile's SSID. Only needed when the new profile deploys a password-based WPA2/WPA3 network. For an 802.1x profile, the certificate handles authentication and this should be left unset. Encrypt it with the Encrypt tool when you do supply it.

• Type: string
• Example:

  --newNetworkPw "ENC:..."

--forgetMigrationNetwork [0|1]

Removes the migration SSID from the Mac's preferred networks once the migration finishes.

• Type: integer
• Choices: 0, 1
• Default: 0
• Example:

  --forgetMigrationNetwork 1

--uninstallTimeout [integer]

Seconds to wait for the old profile to be removed.

• Type: integer
• Default: 300
• Example:

  --uninstallTimeout 300

--installTimeout [integer]

Seconds to wait for the new profile to install.

• Type: integer
• Default: 300
• Example:

  --installTimeout 600

--joinTimeout [integer]

Seconds to keep retrying the join of the new profile's SSID.

• Type: integer
• Default: 300
• Example:

  --joinTimeout 600

--domain [string]

Specifies the domain for setting options in local or managed plists.

• Type: string
• Default: tech.rocketman.networkmigration
• Example:

  --domain "tech.rocketman.customdomain"

JSON Scheme

{
  "title": "Network Migration (tech.rocketman.networkmigration)",
  "description": "Moves a Mac between two 802.1x configuration profiles by swapping its Jamf Pro static group membership, transiting a guest SSID while the profiles are exchanged.",
  "properties": {
    "ssid": {
      "title": "Migration SSID",
      "description": "Broadcasted SSID used while the migration is happening.",
      "type": "string",
      "property_order": 1
    },
    "networkpw": {
      "title": "Migration Network Password",
      "description": "Password for the migration SSID. It is highly recommended to encrypt this using RCC's Encrypt tool.",
      "type": "string",
      "property_order": 2
    },
    "clientId": {
      "title": "Client ID",
      "description": "Client ID for Jamf API authentication. It is recommended to encrypt these credentials using RCC's Encrypt tool.",
      "type": "string",
      "property_order": 3
    },
    "clientSecret": {
      "title": "Client Secret",
      "description": "Client secret for Jamf API authentication. It is highly recommended to encrypt these credentials using RCC's Encrypt tool.",
      "type": "string",
      "property_order": 4
    },
    "removalGroupId": {
      "title": "Removal Group ID",
      "description": "ID of the static computer group scoped in the old profile's exclusions.",
      "type": "integer",
      "property_order": 5
    },
    "targetGroupId": {
      "title": "Target Group ID",
      "description": "ID of the static computer group scoped in the new profile's targets.",
      "type": "integer",
      "property_order": 6
    },
    "oldProfileId": {
      "title": "Old Profile ID",
      "description": "ID of the 802.1x configuration profile being replaced.",
      "type": "integer",
      "property_order": 7
    },
    "newProfileId": {
      "title": "New Profile ID",
      "description": "ID of the 802.1x configuration profile replacing the old one.",
      "type": "integer",
      "property_order": 8
    },
    "computerId": {
      "title": "Computer ID",
      "description": "Jamf computer ID being migrated. When omitted, the Mac is looked up by serial number.",
      "type": "integer",
      "property_order": 9
    },
    "newNetworkPw": {
      "title": "New Network Password",
      "description": "Password for the new profile's SSID. Only needed for a password-based network; leave empty for 802.1x. Encrypt it when supplied.",
      "type": "string",
      "property_order": 10
    },
    "forgetMigrationNetwork": {
      "title": "Forget Migration Network",
      "description": "Set to 1 to remove the migration SSID from the Mac's preferred networks after the migration completes.",
      "type": "integer",
      "default": 0,
      "property_order": 11
    },
    "uninstallTimeout": {
      "title": "Uninstall Timeout",
      "description": "Seconds to wait for the old profile to be removed.",
      "type": "integer",
      "default": 300,
      "property_order": 12
    },
    "installTimeout": {
      "title": "Install Timeout",
      "description": "Seconds to wait for the new profile to install.",
      "type": "integer",
      "default": 300,
      "property_order": 13
    },
    "joinTimeout": {
      "title": "Join Timeout",
      "description": "Seconds to keep retrying the join of the new profile's SSID. Raise this where 802.1x certificate delivery is slow.",
      "type": "integer",
      "default": 300,
      "property_order": 14
    }
  },
  "required": [
    "ssid",
    "networkpw",
    "clientId",
    "clientSecret",
    "removalGroupId",
    "targetGroupId",
    "oldProfileId",
    "newProfileId"
  ]
}