Run a virtual iPhone on an Apple Silicon Mac.
Swift
Stage the kernelcache mix in Launchpad without an ipsw
Maximilian Paßafcbfa5d7f96
diff --git a/Documents/Guides/launchpad-cli.md b/Documents/Guides/launchpad-cli.mdindex 31d81ca2..064cf3c7 100644--- a/Documents/Guides/launchpad-cli.md+++ b/Documents/Guides/launchpad-cli.md@@ -116,7 +116,7 @@ version while a machine is bound to it; rebind or delete those machines first.| `vm list` | Machines in every library with run state, Core Bundle and log path. Only a VM process holding the disk (`vphone-vm`, or Virtualization's VM service) makes a machine `running`; any other process that has it open (`tail`, Spotlight, a backup tool) is listed in `diskOpenIn` (`12925 tail`) and leaves it `stopped` || `vm start <name> [--headless] [--wait]` / `vm stop <name>` | Launch with the machine's bundle, or stop; `--wait` waits for vphoned. Stop asks the guest to shut down (vphoned `system.shutdown`) and waits up to 30 s; when the guest cannot be asked or does not stop, it ends the virtual machine as before. Like `vphone-cli vm launch`, start is not refused by a process that only has the disk open; it prints a note naming it || `vm wait <name>` / `vm log <name> [--kind create\|dfu\|patch]` | Wait for vphoned; read a console log |-| `vm create <name> [--bundle <version>] [...] [--device <product-type>] [--preset <preset>] [--ipsw <path>] [--kmutil-ssh <user@host>] [--block <patch>]... [--allow <patch>]... [--no-template \| --slim on\|off --trim … --keep-languages … --service-profile … --remove-apps … --keep-apps … --accounts-off] [--from <step>]` | The New Machine pipeline, bound to `--bundle` or the default: cloned from a template, built first when missing (2.9), or restored on its own with `--no-template`; the slimming switches are `vphone-cli vm create`'s, except that Apple Account goes with the trimmed service profile as in New Machine (`--accounts-off` is accepted and changes nothing). `--block`/`--allow` (repeatable) turn one patch of the preset off or on, as New Machine's patch list and `vphone-cli fw set-patches` do (see below). `--device` makes an iPad guest, or with `AppleTV5,3` an Apple TV HD guest, which is always restored on its own without slimming and takes the `tvos` preset unless `--preset` names another, and with `AppleTV14,1` an Apple TV 4K guest, the same with the `tvos-4k` preset and its userland from the catalog's OTA; `--preset minimal` (Minimal: a stock boot chain, kernel and TXM, with the system customised before the restore) is also restored on its own without slimming, and its `fw patch` runs as root through the helper; `--ipsw` names the ipsw that stages the kernelcache mix of a machine on its release's own cloudOS, as New Machine's ipsw field (the helper links it as root); `--kmutil-ssh` names the Mac that links an iOS 18 guest's (`--device iPhone11,6`) kernel-first mix over ssh, as New Machine's macOS builder field, and takes the password for ssh and sudo there from the client's `VPHONE_KMUTIL_SSH_PASSWORD`, never from an argument; `--from` retries from a step (`findTemplate` … `firstBoot`) with the options the creation started with; the result names the template, whether this creation built it, and the patches it used |+| `vm create <name> [--bundle <version>] [...] [--device <product-type>] [--preset <preset>] [--ipsw <path>] [--kmutil-ssh <user@host>] [--block <patch>]... [--allow <patch>]... [--no-template \| --slim on\|off --trim … --keep-languages … --service-profile … --remove-apps … --keep-apps … --accounts-off] [--from <step>]` | The New Machine pipeline, bound to `--bundle` or the default: cloned from a template, built first when missing (2.9), or restored on its own with `--no-template`; the slimming switches are `vphone-cli vm create`'s, except that Apple Account goes with the trimmed service profile as in New Machine (`--accounts-off` is accepted and changes nothing). `--block`/`--allow` (repeatable) turn one patch of the preset off or on, as New Machine's patch list and `vphone-cli fw set-patches` do (see below). `--device` makes an iPad guest, or with `AppleTV5,3` an Apple TV HD guest, which is always restored on its own without slimming and takes the `tvos` preset unless `--preset` names another, and with `AppleTV14,1` an Apple TV 4K guest, the same with the `tvos-4k` preset and its userland from the catalog's OTA; `--preset minimal` (Minimal: a stock boot chain, kernel and TXM, with the system customised before the restore) is also restored on its own without slimming, and its `fw patch` runs as root through the helper; the kernelcache mix of a machine whose cloudOS has no vphone600 components (its release's own cloudOS, a watch, an iOS 18 guest) is staged with `fw kernelcache` and linked by the helper as root; `--ipsw` is optional and only passed on to a 2.12.0 bundle, which stages with it, as New Machine's ipsw field (a 2.12.1 bundle extracts natively); `--kmutil-ssh` names the Mac that links an iOS 18 guest's (`--device iPhone11,6`) kernel-first mix over ssh, as New Machine's macOS builder field, and takes the password for ssh and sudo there from the client's `VPHONE_KMUTIL_SSH_PASSWORD`, never from an argument; `--from` retries from a step (`findTemplate` … `firstBoot`) with the options the creation started with; the result names the template, whether this creation built it, and the patches it used || `vm set-bundle <name> <version> [--update-environment]` | Bind a machine to another installed version. `--update-environment` also redeploys that version's guest environment and needs a stopped machine; a disk another process has open refuses it, naming that process, before the binding changes. If the update itself fails, the machine stays bound to the new version and `vm list` still shows the old `guestEnvironmentBundle`: run `cfw update-environment` to finish || `vm leases [--release]` | DHCP leases on the shared NAT network and the machine that owns each. `--release` frees the ones no machine in any library uses, through the helper (see [Networking](networking.md#addresses-held-by-old-macs)) || `cfw install <name>` | Install CFW into a stopped machine with its own bundle, through the helper. The helper puts temporary work files on the VM library's external volume when applicable. It and the two updates below refuse a disk another process has open, naming it (`12925 tail`). |diff --git a/VPhoneLaunchpad/VPhoneLaunchpad/Control/VPhoneLaunchpadControlCommands.swift b/VPhoneLaunchpad/VPhoneLaunchpad/Control/VPhoneLaunchpadControlCommands.swiftindex 2028e7d4..00a9bb6c 100644--- a/VPhoneLaunchpad/VPhoneLaunchpad/Control/VPhoneLaunchpadControlCommands.swift+++ b/VPhoneLaunchpad/VPhoneLaunchpad/Control/VPhoneLaunchpadControlCommands.swift@@ -615,8 +615,9 @@ struct VPhoneLaunchpadControlCommands {} else {slimming = try Self.slimming(request, usesTemplate: usesTemplate)}- // A machine on its release's own cloudOS stages its kernelcache mix with- // an ipsw, as New Machine's ipsw field; `fw kernelcache` does nothing+ // A 2.12.0 bundle stages a kernelcache mix with an ipsw, as New+ // Machine's ipsw field; a 2.12.1 bundle extracts natively and ignores+ // it. The creation runs `fw kernelcache` either way, which does nothing// on a cloudOS that still has vphone600 components.let kernelcacheIPSW = request.option("ipsw")if let kernelcacheIPSW, !FileManager.default.isExecutableFile(atPath: kernelcacheIPSW) {@@ -632,9 +633,6 @@ struct VPhoneLaunchpadControlCommands {guard VPhoneLaunchpadKernelcacheBuilder.isValid(kernelcacheBuilder.destination) else {throw VPhoneLaunchpadError("--kmutil-ssh takes user@host, not \(kernelcacheBuilder.destination).")}- guard kernelcacheIPSW != nil else {- throw VPhoneLaunchpadError("--kmutil-ssh links the kernelcache mix that --ipsw stages; pass --ipsw too.")- }}let options = try VPhoneLaunchpadCreationPipeline.Options(name: machine.name,diff --git a/VPhoneLaunchpad/VPhoneLaunchpad/Machines/VPhoneLaunchpadCreationPipeline.swift b/VPhoneLaunchpad/VPhoneLaunchpad/Machines/VPhoneLaunchpadCreationPipeline.swiftindex 7374a6fe..8d83657e 100644--- a/VPhoneLaunchpad/VPhoneLaunchpad/Machines/VPhoneLaunchpadCreationPipeline.swift+++ b/VPhoneLaunchpad/VPhoneLaunchpad/Machines/VPhoneLaunchpadCreationPipeline.swift@@ -99,9 +99,9 @@ final class VPhoneLaunchpadCreationPipeline {/// of its own.var usesTemplate = truevar slimming = VPhoneLaunchpadSlimming()- /// The ipsw that stages the kernelcache mix of a machine on its- /// release's own cloudOS (`fw kernelcache --ipsw`), whose link the helper- /// runs as root. Nil for every other machine.+ /// The ipsw a 2.12.0 bundle stages the kernelcache mix with (`fw+ /// kernelcache --ipsw`), whose link the helper runs as root. A 2.12.1+ /// bundle extracts natively and ignores it; nil passes none.var kernelcacheIPSW: String?/// The Mac that links a kernel-first mix over ssh, for an iOS 18 guest/// on a Mac whose kmutil links kernel-last; nil links here, as root.@@ -395,16 +395,17 @@ final class VPhoneLaunchpadCreationPipeline {let log = loglet output: @Sendable (String) -> Void = { line in log.write(line) }+ @discardableResultfunc run(_ arguments: [String],builder: VPhoneLaunchpadKernelcacheBuilder? = nil,onLine: @escaping @Sendable (String) -> Void = output,onProgress: (@Sendable (Double) -> Void)? = nil,- ) async throws {+ ) async throws -> VPhoneLaunchpadCommandResult {// The builder's destination is shown, its password is not.let prefix = builder.map { "\(VPhoneLaunchpadKernelcacheBuilder.destinationVariable)=\($0.destination) " } ?? ""onLine("$ \(prefix)\(VPhoneLaunchpadCommandLine.display(arguments))")- try await commandLine.runChecked(arguments, environment: builder?.environment ?? [:], onLine: onLine, onProgress: onProgress)+ return try await commandLine.runChecked(arguments, environment: builder?.environment ?? [:], onLine: onLine, onProgress: onProgress)}// For the template steps: a failure names the step and carries the@@ -491,15 +492,21 @@ final class VPhoneLaunchpadCreationPipeline {)}let libraryRoot = Self.canonicalPath(URL(fileURLWithPath: options.libraryRoot, isDirectory: true))- // On the release's own cloudOS the kernelcache is mixed first: staged- // here, as the user, with the chosen ipsw, and linked by the helper as- // root, which runs no ipsw. `fw patch` takes the mix from the cache.- // With an ssh builder, `fw kernelcache` links it on that Mac, and- // nothing here needs root for it.- if let ipsw = options.kernelcacheIPSW, let builder = options.kernelcacheBuilder {- try await run(["fw", "kernelcache", name, "--ipsw", ipsw] + library, builder: builder, onLine: tee)- } else if let ipsw = options.kernelcacheIPSW {- try await run(["fw", "kernelcache", name, "--ipsw", ipsw] + library, onLine: tee)+ // A machine whose cloudOS has no vphone600 components (the release's+ // own cloudOS, a watch, an iOS 18 guest) gets its kernelcache mixed+ // first: staged here, as the user, and linked by the helper as root.+ // `fw patch` takes the mix from the cache. `fw kernelcache` decides+ // whether a mix is needed and says "[=] … needs no mix" otherwise,+ // so it runs for every machine: since 2.12.1 it extracts natively,+ // and the ipsw is only passed on for a 2.12.0 bundle, which needs+ // one. The helper runs only once a volume is staged ("[+] Staged."),+ // so a machine without a mix asks for no administrator access. With+ // an ssh builder, `fw kernelcache` links it on that Mac, and nothing+ // here needs root for it.+ let kernelcache = ["fw", "kernelcache", name] + (options.kernelcacheIPSW.map { ["--ipsw", $0] } ?? []) + library+ if let builder = options.kernelcacheBuilder {+ try await run(kernelcache, builder: builder, onLine: tee)+ } else if try await run(kernelcache, onLine: tee).lines.contains(where: { $0.hasPrefix("[+] Staged.") }) {let status = try await helper.linkKernelcache(bundleVersion: version,machineName: name,diff --git a/VPhoneLaunchpad/VPhoneLaunchpad/Machines/VPhoneLaunchpadNewMachineView.swift b/VPhoneLaunchpad/VPhoneLaunchpad/Machines/VPhoneLaunchpadNewMachineView.swiftindex 4473c044..7316df29 100644--- a/VPhoneLaunchpad/VPhoneLaunchpad/Machines/VPhoneLaunchpadNewMachineView.swift+++ b/VPhoneLaunchpad/VPhoneLaunchpad/Machines/VPhoneLaunchpadNewMachineView.swift@@ -105,7 +105,8 @@ struct VPhoneLaunchpadNewMachineView: View {usesOwnCloudOS && !usesCustomSources ? selectedPairing?.matchingCloudOS : nil}- /// Whether `fw patch` rebuilds the kernelcache, which needs the ipsw: on+ /// Whether `fw patch` rebuilds the kernelcache, which a 2.12.0 bundle+ /// stages with the ipsw (a 2.12.1 one extracts natively): on/// the release's own cloudOS, always for a watch, whose kexts no cloudOS/// kernelcache has, and for an iOS 18 guest, which boots its own release's/// research board kernel.@@ -235,7 +236,7 @@ struct VPhoneLaunchpadNewMachineView: View {private var canCreate: Bool {nameProblem == nil && advancedProblem == nil && sources != nil && bundleVersion != nil&& (!usesCustomSources || inspectedCustomSource == iphoneSource)- && (!rebuildsKernelcache || hasKernelcacheIPSW) && kernelcacheBuilderProblem == nil+ && kernelcacheBuilderProblem == nil}var body: some View {@@ -486,24 +487,18 @@ struct VPhoneLaunchpadNewMachineView: View {Text("Choose a guest IPSW and a cloudOS IPSW in Advanced Options.").foregroundStyle(.red)}} else if let own = ownCloudOS {- Text(hasKernelcacheIPSW- ? "On its own cloudOS, \(own.name): the kernelcache is rebuilt, which asks for administrator access once."- : "Choose an ipsw with `kernel extract --kdk` in Advanced Options to run on \(own.name).")- .foregroundStyle(hasKernelcacheIPSW ? Color.secondary : Color.red)+ Text("On its own cloudOS, \(own.name): the kernelcache is rebuilt, which asks for administrator access once.")+ .foregroundStyle(.secondary)} else if linksKernelFirst, let cloudOS = selectedPairing?.recommendedCloudOS.name {- if !hasKernelcacheIPSW {- Text("Choose an ipsw with `kernel extract --kdk` in Advanced Options: the release's own kernel is rebuilt with the vphone600 kexts.").foregroundStyle(.red)- } else if let kernelcacheBuilderProblem {+ if let kernelcacheBuilderProblem {Text(kernelcacheBuilderProblem).foregroundStyle(.red)} else {Text("With \(cloudOS): the kernelcache is rebuilt and linked \(kernelcacheBuilder.map { "on \($0.destination)" } ?? "on this Mac"), and the restore image asks for administrator access once.").foregroundStyle(.secondary)}} else if rebuildsKernelcache, let cloudOS = selectedPairing?.recommendedCloudOS.name {- Text(hasKernelcacheIPSW- ? "With \(cloudOS): the kernelcache is rebuilt with the watch's kexts, which asks for administrator access once."- : "Choose an ipsw with `kernel extract --kdk` in Advanced Options: the watch's kernelcache is rebuilt with its kexts.")- .foregroundStyle(hasKernelcacheIPSW ? Color.secondary : Color.red)+ Text("With \(cloudOS): the kernelcache is rebuilt with the watch's kexts, which asks for administrator access once.")+ .foregroundStyle(.secondary)} else if let selectedGuest, let cloudOS = selectedPairing?.recommendedCloudOS.name {Text("Recommended firmware pairings for \(selectedGuest.detailedName), with \(cloudOS).").foregroundStyle(.secondary)@@ -702,11 +697,11 @@ struct VPhoneLaunchpadNewMachineView: View {Text(usesCustomSources? "These two files replace the device and version chosen on the basic page.": ownCloudOS != nil- ? "On its own cloudOS the release boots its own kernel, rebuilt with the vphone600 virtualisation kexts: the ipsw (with `kernel extract --kdk`) stages it as you, and the helper links it as root."+ ? "On its own cloudOS the release boots its own kernel, rebuilt with the vphone600 virtualisation kexts: it is staged as you, and the helper links it as root. The ipsw (with `kernel extract --kdk`) is only needed by a 2.12.0 Core Bundle.": linksKernelFirst- ? "iOS 18 boots its own release's kernel, rebuilt with the vphone600 kexts of cloudOS 26.1: the ipsw (with `kernel extract --kdk`) stages it as you. Only the kmutil of macOS 15 or 26.0 to 26.3 links it: from macOS 26.4 on, the macOS builder, a Mac or macOS VM with Remote Login on, links it over ssh as root there. The password is for ssh and sudo on it and is not saved; leave it empty with ssh keys and passwordless sudo."+ ? "iOS 18 boots its own release's kernel, rebuilt with the vphone600 kexts of cloudOS 26.1: it is staged as you (a 2.12.0 Core Bundle needs the ipsw with `kernel extract --kdk` for that). Only the kmutil of macOS 15 or 26.0 to 26.3 links it: from macOS 26.4 on, the macOS builder, a Mac or macOS VM with Remote Login on, links it over ssh as root there. The password is for ssh and sudo on it and is not saved; leave it empty with ssh keys and passwordless sudo.": rebuildsKernelcache- ? "A watch boots the cloudOS kernel rebuilt with its own kexts: the ipsw (with `kernel extract --kdk`) stages it as you, and the helper links it as root."+ ? "A watch boots the cloudOS kernel rebuilt with its own kexts: it is staged as you, and the helper links it as root. The ipsw (with `kernel extract --kdk`) is only needed by a 2.12.0 Core Bundle.": "The device and version are chosen on the basic page; cloudOS goes with them.").foregroundStyle(.secondary)}@@ -929,7 +924,7 @@ struct VPhoneLaunchpadNewMachineView: View {keepArtifacts: keepArtifacts,usesTemplate: usesTemplate,slimming: slimming,- kernelcacheIPSW: rebuildsKernelcache ? kernelcacheIPSW : nil,+ kernelcacheIPSW: rebuildsKernelcache && hasKernelcacheIPSW ? kernelcacheIPSW : nil,kernelcacheBuilder: kernelcacheBuilder,)let pipeline = model.machines.create(options)diff --git a/VPhoneLaunchpad/VPhoneLaunchpadShared/VPhoneLaunchpadControl.swift b/VPhoneLaunchpad/VPhoneLaunchpadShared/VPhoneLaunchpadControl.swiftindex c634abff..b7e7675d 100644--- a/VPhoneLaunchpad/VPhoneLaunchpadShared/VPhoneLaunchpadControl.swift+++ b/VPhoneLaunchpad/VPhoneLaunchpadShared/VPhoneLaunchpadControl.swift@@ -184,7 +184,7 @@ nonisolated struct VPhoneLaunchpadControlCommand: Sendable {"root", "bundle", "iphone-source", "cloudos-source", "device", "cpu", "memory", "disk-size", "network", "preset", "from", "ipsw", "kmutil-ssh","slim", "trim", "keep-languages", "service-profile", "remove-apps", "keep-apps",], flags: ["keep-artifacts", "no-wait", "no-template", "accounts-off"], repeated: ["block", "allow"],- summary: "Create a machine through every step, as New Machine does, bound to --bundle (default: the default bundle): cloned from a template, built first when missing, or restored on its own with --no-template. --block and --allow turn one patch of --preset off or on, as New Machine's patch list and vphone-cli fw set-patches do: boot-chain ones go into the template, guest ones are applied to the clone. --slim, --trim, --keep-languages, --service-profile, --remove-apps, --keep-apps and --accounts-off shape the template, as in vphone-cli vm create. --ipsw <path> stages the kernelcache mix of a machine on its release's own cloudOS, as New Machine's ipsw field. --kmutil-ssh <user@host> links an iOS 18 guest's kernel-first mix on that Mac over ssh, as New Machine's macOS builder field, with the password (for ssh and sudo there) from this tool's VPHONE_KMUTIL_SSH_PASSWORD. --from <step> retries a failed creation from that step, with the options it started with."),+ summary: "Create a machine through every step, as New Machine does, bound to --bundle (default: the default bundle): cloned from a template, built first when missing, or restored on its own with --no-template. --block and --allow turn one patch of --preset off or on, as New Machine's patch list and vphone-cli fw set-patches do: boot-chain ones go into the template, guest ones are applied to the clone. --slim, --trim, --keep-languages, --service-profile, --remove-apps, --keep-apps and --accounts-off shape the template, as in vphone-cli vm create. --ipsw <path> is the ipsw a 2.12.0 bundle stages a kernelcache mix with, as New Machine's ipsw field; a 2.12.1 bundle extracts natively and needs none. --kmutil-ssh <user@host> links an iOS 18 guest's kernel-first mix on that Mac over ssh, as New Machine's macOS builder field, with the password (for ssh and sudo there) from this tool's VPHONE_KMUTIL_SSH_PASSWORD. --from <step> retries a failed creation from that step, with the options it started with."),Self(name: "vm.set-bundle", arguments: ["name", "version"], options: ["root"], flags: ["update-environment"],summary: "Bind a machine to another installed version; its host programs change at the next start. --update-environment also redeploys that version's guest environment into the stopped machine. The boot chain stays as created."),Self(name: "vm.leases", arguments: [], options: [], flags: ["release"],