Managing airgapped ios devices

docs/modules/device-lab-management/nav.adoc

@@ -15,4 +15,5 @@
 ** xref:android-devices/prepare-android-device.adoc[]
 ** xref:android-devices/add-android-device.adoc[]
 * Standalone/On-Prem
-** xref:standalone/collect-standalone-logs.adoc[]
+** xref:standalone/collect-standalone-logs.adoc[]
+** xref:standalone/managing-airgapped-ios-devices.adoc[]

docs/modules/device-lab-management/pages/ios-devices/add-ios-device.adoc

@@ -158,6 +158,8 @@ Wait until the device screen changes to the below before continuing. There will
 
 image::device-lab-management:device-lab-management-add-android-screen-changes-to-blue.PNG[width=300, alt="device screen changes and shows Kobiton name and logo"]
 
+
+
 [#preload-ddi-air-gapped]
 === Preload DDI for air-gapped Mac mini hosts
 
@@ -169,40 +171,42 @@ Access any macOS machine with Internet access. This will be referred to as the I
 [NOTE]
 Kobiton software, such as deviceConnect and deviceShare, does not need to be installed on the Internet Mac.
 
-Ensure *Xcode* is installed on the Internet Mac. Make sure the Xcode version is compatible with the iOS 17 device.
+Ensure *Xcode* is installed on the Internet Mac. Make sure the Xcode version on the Internet Mac is the same as the air-gapped Mac.
 
 [IMPORTANT]
 Make sure the Xcode version on the Internet Mac *is the same or greater* than the version on the Mac mini host to transfer the DDI to.
 
-Unplug the iOS 17 device from the air-gapped Mac (Standard mode) or the GEM (Lightning mode) and connect it to the Internet Mac.
+Unplug the iOS 17 and above device from the air-gapped Mac (Standard mode) or the GEM (Lightning mode) and connect it to the Internet Mac.
 
 Open Xcode.
 
-Tap Trust in the **Trust this computer** popup on the iOS 17 device. The **Trust this computer** prompts will reappear, tap **Trust** again. After this, there should be no more **Trust** prompts.
+Tap Trust in the **Trust this computer** popup on the iOS 17 and above device. The **Trust this computer** prompts will reappear, tap **Trust** again. After this, there should be no more **Trust** prompts.
 
-In the Xcode menu bar, select **Window → Devices and Simulators**. Select the iOS 17 device under the **Devices** tab.
+In the Xcode menu bar, select **Window → Devices and Simulators**. Select the iOS 17 and above device under the **Devices** tab.
 
 The `Copying shared cache symbols...` message appears. Wait for this process to complete and the message to clear.
 
 image::device-lab-management:device-lab-management-ios-add-ios-copying-shared-cache-symbols.PNG[width=600,alt="Copying shared cache symbols"]
 
 Unplug the device from the Internet Mac.
 
-Repeat the above processes for all iOS/iPadOS 17 and later devices to be hosted on the air-gapped Mac mini.
+Repeat the above processes for all iOS/iPadOS 17 and above devices to be hosted on the air-gapped Mac mini.
+
+// tag::ddi[]
 
 Open *Finder* on the Internet Mac. Press *Shift + Command + G* on the keyboard, then input the following path depending on the version of Xcode:
 
-* `/Library/Developer/DeveloperDiskImages` (Xcode 16 and above)
+* `/Library/Developer/CoreDevice/CandidateDDIs/iOS_DDI.dmg` or `~/Library/Developer/CoreDevice/CandidateDDIs/iOS_DDI.dmg` (Xcode 16.3 and newer)
 
-* `~/Library/Developer/DeveloperDiskImages` (Xcode below 16)
+* `/Library/Developer/DeveloperDiskImages` (Xcode 16 to 16.2)
 
-Copy the 2 files `iOS_DDI-version.plist` and `iOS_DDI.dmg` to the *air-gapped Mac mini* that will host the iOS/iPadOS 17 and later devices. Put the copied file into the following folder on the air-gapped Mac mini:
+* `~/Library/Developer/DeveloperDiskImages` (Xcode below 16)
 
-* `/Library/Developer/DeveloperDiskImages` if the current Xcode version is 16 or above.
+Copy the 2 files `iOS_DDI-version.plist` and `iOS_DDI.dmg` to the same location on the *air-gapped Mac mini* that will host the iOS/iPadOS 17 and above devices.
 
-* ``~/Library/Developer/DeveloperDiskImages ``if the current Xcode version is below 16.
+// end::ddi[]
 
-Repeat the above process for all air-gapped Mac mini hosts with iOS/iPadOS 17 and later devices.
+Repeat the above process for all air-gapped Mac mini hosts with iOS/iPadOS 17 and above devices.
 
 Continue with connecting iOS 17 and above devices to the air-gapped Mac mini hosts or the GEM.
 

docs/modules/device-lab-management/pages/standalone/managing-airgapped-ios-devices.adoc

@@ -0,0 +1,89 @@
+= Managing iOS Devices in Air‑Gapped Kobiton Environments
+
+:navtitle: Managing iOS Devices in Air-Gapped Environments
+
+This document outlines Kobiton’s standardized process for enabling iOS device management within air‑gapped environments—data centers or secured labs isolated from the internet. It addresses Apple’s security requirements (e.g., personalized Developer Disk Images and certificate verification) and provides step-by-step guidance to maintain device operability without compromising security.
+
+== Requirements from Apple
+
+* **Developer Certificate Verification**
+
++
+
+Apple requires all provisioning profiles and signing certificates to be verified against their servers on first installation. This validation must occur online at least once. Subsequent launches will rely on cached credentials.
+
+* **Personalized Developer Disk Image (DDI)**
+
++
+
+For iOS 17+, each device requires a unique, Apple‑personalized DDI via a TSS request to Apple servers (https://gs.apple.com/TSS). This signature is stored locally on the device and does not require internet access after the initial retrieval—but may expire over time.
+
+== Process Overview
+
+=== Initial Setup & Certificate Verification
+
+* Prepare a **dedicated, internet‑connected macOS host** with supported Xcode (e.g., Xcode 16.4 on macOS 15.5).
+
+* Connect each iOS device via **USB** and enable Developer Mode.
+
+* Launch Xcode with the device active and foregrounded to establish trust and verify the certificate.
+
+=== Personalized DDI Acquisition
+
+* For each iOS 17+ device:
+** Connect via USB to the internet‑connected macOS host.
+** Let Xcode request and download the personalized DDI signature from Apple.
+** Confirm that the personalization ticket is recorded locally on the device.
+
+=== Air‑Gapped Deployment
+
+* Remove the device from the online macOS host.
+* Connect it via USB or Cambrionix hub to the air‑gapped Kobiton device host.
+* xref:device-lab-management:deviceConnect/restart-deviceconnect-services.adoc[Restart deviceConnect services,window=read-later] on the Mac mini to mount and load the DDI.
+* If verification fails, reconnect the device to the internet‑enabled host and refresh credentials.
+
+=== Air‑Gapped Deployment DDI Transfer
+
+For air-gapped or datacenter environments where it’s cumbersome to follow manual steps to allow Xcode to download this file, administrators can copy the base image from the Internet macOS host to the air-gapped host.
+
+Follow the steps from the previous sections to generate the DDI on the Internet host.
+
+include::device-lab-management:ios-devices/add-ios-device.adoc[tag=ddi]
+
+=== Monitoring & Remediation
+
+Kobiton logs will alert on:
+
+* DDI mount failures.
+* `deviceControl` (Kobiton mobile agent) launch issues.
+
+These typically indicate expired credentials or missing certificates. In such cases, repeat the steps in the _Personalized DDI Acquisition_ and _Air‑Gapped Deployment_ sections.
+
+== System Administrator Checklist
+
+* A secure macOS machine with **Xcode installed** and internet access.
+* iOS devices connected via USB with **Developer Mode enabled**.
+* Kobiton’s `deviceConnect` deployed on air‑gapped hosts.
+* Physical USB access to devices in the lab while maintaining network isolation.
+
+== Troubleshooting & Common Errors
+
+[cols="1,2,3", options="header"]
+|===
+| Symptom                     | Likely Cause                | Recommended Action
+| `deviceControl failed to launch` | Certificate expired or missing provisioning | Reconnect to internet host and re-verify certificate
+| `DDI mount error`          | Missing or expired personalization ticket | Repeat personalized DDI process via internet host
+| New device not recognized  | No provisioning profile or mismatched certificate | Update provisioning, ensure UDID is included
+|===
+
+== Future Enhancements
+Kobiton plans to store **personalization tickets per device** by default—reducing dependency on initial setup hosts and supporting multi-node labs more robustly.
+
+== Summary
+Kobiton’s process enables secure iOS device management in air‑gapped environments by:
+
+* Using an online macOS host for Apple compliance steps
+* Mounting devices offline following credential and DDI setup
+* Maintaining a repeatable, compliant workflow even as Apple's requirements evolve
+
+For detailed configuration, USB hub setup guidance, provisioning profile help, or Kobiton log analysis, consult the official Kobiton documentation or contact support.