Skip to content

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.md
index 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.swift
index 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.swift
index 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 = true
var 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 = log
let output: @Sendable (String) -> Void = { line in log.write(line) }
+ @discardableResult
func 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.swift
index 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.swift
index 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"],