Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Use external volume for CFW scratch space

竺笙6b55fedbd17a
diff --git a/Documents/Downloads/README.md b/Documents/Downloads/README.md
index 7d6fe021..a5c027ce 100644
--- a/Documents/Downloads/README.md
+++ b/Documents/Downloads/README.md
@@ -32,6 +32,7 @@ Use a `VPhone.bundle` from the same series as Launchpad. The series is the first
| Launchpad | VPhone.bundle |
| --- | --- |
+| 2.9.x | 2.9.x |
| 2.8.x | 2.8.x |
| 2.7.x | 2.7.x |
| 2.6.x | 2.6.x |
diff --git a/Documents/Guides/create-and-run.md b/Documents/Guides/create-and-run.md
index 7c4e67c6..63d0c2b9 100644
--- a/Documents/Guides/create-and-run.md
+++ b/Documents/Guides/create-and-run.md
@@ -84,4 +84,4 @@ vphone-cli vm import myphone.tzst --name restored
Do not swap `SEPStorage`, `nvram.bin` or the disk image between machines: they were made together by one restore, and a guest whose SEP storage does not match its disk panics at boot.
-Run resource-heavy creations **one at a time**. Both the IPSWs and temporary restore tree consume substantial disk space, and patching large caches can be memory intensive. Check free space before starting a second VM.
+Run resource-heavy creations **one at a time**. Both the IPSWs and temporary restore tree consume substantial disk space, and patching large caches can be memory intensive. Check free space before starting a second VM. Launchpad places CFW scratch files on the VM library's mounted external volume when applicable; standalone `vphone-cli cfw install` defaults to `/private/var/tmp` and accepts `--work-parent` for a root-owned private directory.
diff --git a/Documents/Guides/launchpad-cli.md b/Documents/Guides/launchpad-cli.md
index dea232f8..4ffa0a9b 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 create <name> [--bundle <version>] [...] [--device <product-type>] [--from <step>]` | The New Machine pipeline, bound to `--bundle` or the default; `--device` makes an iPad guest, `--from` retries from a step |
| `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 |
| `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 |
+| `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. |
| `cfw update-environment <name>` | Redeploy the machine's own bundle's guest resources (vphoned, hook dylibs) into it while stopped, through the helper; nothing else changes |
| `cfw update-kernel <name>` | Re-patch the kernelcache from the machine's current selection and swap it into Preboot, keeping the data (VM off); the data-preserving way to change a kernel patch on an installed VM, no restore tree needed |
| `guest send <name> <json>` | One raw `vphone.sock` request (tap, swipe, key, screenshot) |
diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift
index 43285d91..3fd69ff1 100644
--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift
@@ -68,6 +68,7 @@ struct VPhoneCustomFirmwareInstaller {
let bundle: URL
let resources: VPhoneResources
var mode: Mode = .full
+ let workParent: String
/// Guest system files belong to root:wheel.
private static let guestOwner: (uid: uid_t, gid: gid_t) = (0, 0)
@@ -86,7 +87,7 @@ struct VPhoneCustomFirmwareInstaller {
/// Root-owned and sticky, outside every user's tree. The work folder is
/// made here with `mkdtemp`, so its name cannot be predicted or claimed.
- private static let workParent = "/private/var/tmp"
+ static let defaultWorkParent = "/private/var/tmp"
private var executable: URL {
VPhoneResources.runningExecutable()
@@ -107,9 +108,15 @@ struct VPhoneCustomFirmwareInstaller {
bundle: URL,
resources: VPhoneResources,
mode: Mode = .full,
+ workParent: String = defaultWorkParent,
) throws -> Int32 {
if geteuid() == 0 {
- try VPhoneCustomFirmwareInstaller(bundle: bundle, resources: resources, mode: mode).run()
+ try VPhoneCustomFirmwareInstaller(
+ bundle: bundle,
+ resources: resources,
+ mode: mode,
+ workParent: workParent,
+ ).run()
return 0
}
throw ValidationError("\(mode.summary.capitalized) needs root. Run this command with sudo.")
@@ -2512,7 +2519,14 @@ struct VPhoneCustomFirmwareInstaller {
// MARK: - Cleanup
private func makeWorkDirectory() throws -> WorkDirectory {
- var template = Array("\(Self.workParent)/vphone-cfw.XXXXXXXX".utf8CString)
+ let parent = try VPhoneConfinedDirectory.pin(absolutePath: workParent, requireOwner: 0)
+ let parentMode = try parent.metadata().st_mode & 0o7777
+ let privateDirectory = parentMode & 0o077 == 0
+ let stickySharedDirectory = parentMode & 0o1777 == 0o1777
+ guard privateDirectory || stickySharedDirectory else {
+ throw ValidationError("The CFW work folder parent \(workParent) must be root-owned and private or sticky.")
+ }
+ var template = Array("\(workParent)/vphone-cfw.XXXXXXXX".utf8CString)
// mkdtemp returns a pointer into the template. `&template` lends only a
// temporary buffer that ends with the call, and the array is dead after
// it, so read the name while the buffer is still pinned.
@@ -2520,7 +2534,7 @@ struct VPhoneCustomFirmwareInstaller {
mkdtemp(buffer.baseAddress!).map { String(cString: $0) }
}
guard let path = created else {
- throw ValidationError("Unable to create a private work folder in \(Self.workParent): \(String(cString: strerror(errno)))")
+ throw ValidationError("Unable to create a private work folder in \(workParent): \(String(cString: strerror(errno)))")
}
// mkdtemp creates the folder 0700 for its caller, root. Re-check it
// through a no-follow walk before mounting anything under it.
@@ -2554,7 +2568,7 @@ struct VPhoneCustomFirmwareInstaller {
else {
throw ValidationError("A CFW volume is still mounted under \(work.url.path). Eject it, then try again.")
}
- try VPhoneConfinedDirectory.pin(absolutePath: Self.workParent).removeItem(work.name)
+ try VPhoneConfinedDirectory.pin(absolutePath: workParent).removeItem(work.name)
}
private func detachImage(at mount: URL) throws {
@@ -2601,11 +2615,14 @@ struct VPhoneCustomFirmwareInstallRootCommand: ParsableCommand {
@Argument(help: "VM bundle path") var bundle: String
@Option(help: "Resource base") var resources: String
+ @Option(name: .customLong("work-parent"), help: "Root-owned private CFW temporary directory")
+ var workParent = VPhoneCustomFirmwareInstaller.defaultWorkParent
func run() throws {
try VPhoneCustomFirmwareInstaller(
bundle: URL(fileURLWithPath: bundle),
resources: VPhoneResources(base: URL(fileURLWithPath: resources)),
+ workParent: workParent,
).run()
}
}
diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Restore/VPhoneRestoreCommand.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Restore/VPhoneRestoreCommand.swift
index c87b41e5..80e6513c 100644
--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Restore/VPhoneRestoreCommand.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Restore/VPhoneRestoreCommand.swift
@@ -316,6 +316,8 @@ struct VPhoneCustomFirmwareInstallCommand: ParsableCommand {
help: "Keep the extracted firmware after install (default: removed to save space)",
)
var keepArtifacts = false
+ @Option(name: .customLong("work-parent"), help: "Root-owned private CFW temporary directory")
+ var workParent = VPhoneCustomFirmwareInstaller.defaultWorkParent
func run() throws {
let name = try VPhoneVirtualMachineSelection.resolveExisting(name, in: lib.library)
@@ -325,6 +327,7 @@ struct VPhoneCustomFirmwareInstallCommand: ParsableCommand {
let code = try VPhoneCustomFirmwareInstaller.elevate(
bundle: bundle.url,
resources: resources,
+ workParent: workParent,
)
if code == 0 {
try recordInstall(in: bundle)
diff --git a/VPhoneExecutable/VPhoneVirtualization/Resources/Info.plist b/VPhoneExecutable/VPhoneVirtualization/Resources/Info.plist
index c9d58434..a6e96e51 100644
--- a/VPhoneExecutable/VPhoneVirtualization/Resources/Info.plist
+++ b/VPhoneExecutable/VPhoneVirtualization/Resources/Info.plist
@@ -11,7 +11,7 @@
<key>CFBundleVersion</key>
<string>35</string>
<key>CFBundleShortVersionString</key>
- <string>2.8.0</string>
+ <string>2.9.0</string>
<key>NSMicrophoneUsageDescription</key>
<string>Shares this Mac's microphone with the virtual iPhone so apps running inside it can record.</string>
</dict>
diff --git a/VPhoneLaunchpad/Configuration/Version.xcconfig b/VPhoneLaunchpad/Configuration/Version.xcconfig
index 5bc48b7c..5973746c 100644
--- a/VPhoneLaunchpad/Configuration/Version.xcconfig
+++ b/VPhoneLaunchpad/Configuration/Version.xcconfig
@@ -1,4 +1,4 @@
-MARKETING_VERSION = 2.8.0
+MARKETING_VERSION = 2.9.0
// Bump whenever the helper changes. The app blesses the helper again when the
// installed helper's version or bytes differ from the copy it embeds.
-CURRENT_PROJECT_VERSION = 15
+CURRENT_PROJECT_VERSION = 16
diff --git a/VPhoneLaunchpad/VPhoneLaunchpadHelper/VPhoneLaunchpadHelperFirmwareRequest.swift b/VPhoneLaunchpad/VPhoneLaunchpadHelper/VPhoneLaunchpadHelperFirmwareRequest.swift
index 69f28306..69d5b098 100644
--- a/VPhoneLaunchpad/VPhoneLaunchpadHelper/VPhoneLaunchpadHelperFirmwareRequest.swift
+++ b/VPhoneLaunchpad/VPhoneLaunchpadHelper/VPhoneLaunchpadHelperFirmwareRequest.swift
@@ -17,9 +17,10 @@ struct VPhoneLaunchpadHelperFirmwareRequest {
typealias MachineKey = VPhoneLaunchpadHelperFirmwareAdmission.MachineKey
- /// The installer's work parent, `VPhoneCustomFirmwareInstaller.workParent`:
- /// every run makes its private work folder there.
- static let workParent = "/private/var/tmp"
+ /// CFW keeps its scratch files beside the VM when that VM is on a mounted
+ /// external volume. The child directory is root-owned and private. Internal
+ /// libraries retain the system temporary directory.
+ static let defaultWorkParent = "/private/var/tmp"
let executable: URL
let arguments: [String]
@@ -58,22 +59,30 @@ struct VPhoneLaunchpadHelperFirmwareRequest {
let folder = try Self.requireMachine(libraryRoot: libraryRoot, machineName: machineName, ownedBy: callerUID)
let machine = URL(fileURLWithPath: libraryRoot, isDirectory: true)
.appendingPathComponent(machineName, isDirectory: true)
+ let workParent = try Self.resolveWorkParent(
+ libraryRoot: libraryRoot,
+ callerUID: callerUID,
+ callerGID: callerGID,
+ )
var work = stat()
- guard stat(Self.workParent, &work) == 0 else {
- throw VPhoneLaunchpadHelperError("Unable to read \(Self.workParent): \(String(cString: strerror(errno)))")
+ guard stat(workParent, &work) == 0 else {
+ throw VPhoneLaunchpadHelperError("Unable to read \(workParent): \(String(cString: strerror(errno)))")
}
var arguments: [String]
switch operation {
case let .install(keepArtifacts):
- arguments = ["cfw", "install", machineName, "--library-root", libraryRoot]
+ arguments = ["cfw", "install", machineName, "--library-root", libraryRoot,
+ "--work-parent", workParent]
if keepArtifacts {
arguments.append("--keep-artifacts")
}
case .updateEnvironment:
- arguments = ["cfw", "update-environment", machineName, "--library-root", libraryRoot]
+ arguments = ["cfw", "update-environment", machineName, "--library-root", libraryRoot,
+ "--work-parent", workParent]
case .updateKernel:
- arguments = ["cfw", "update-kernel", machineName, "--library-root", libraryRoot]
+ arguments = ["cfw", "update-kernel", machineName, "--library-root", libraryRoot,
+ "--work-parent", workParent]
}
self.executable = executable
@@ -81,7 +90,7 @@ struct VPhoneLaunchpadHelperFirmwareRequest {
workingDirectory = machine
machineKey = MachineKey(device: folder.st_dev, inode: folder.st_ino)
// Not one literal: equal keys in a dictionary literal trap.
- var volumes = [work.st_dev: Self.workParent]
+ var volumes = [work.st_dev: workParent]
volumes[folder.st_dev] = machine.path
self.volumes = volumes
// The same environment `sudo vphone-cli cfw install` sees: SUDO_UID
@@ -90,6 +99,83 @@ struct VPhoneLaunchpadHelperFirmwareRequest {
environment = try VPhoneLaunchpadHelperLibraryPath.environment(callerUID: callerUID, callerGID: callerGID)
}
+ /// Selects a protected scratch directory on the VM's mounted external
+ /// volume. A user-writable volume root is refused: root must not create a
+ /// directory where the caller can race or replace it.
+ private static func resolveWorkParent(
+ libraryRoot: String,
+ callerUID: uid_t,
+ callerGID: gid_t,
+ ) throws -> String {
+ let library = try VPhoneLaunchpadHelperLibraryPath.openDirectory(libraryRoot)
+ defer { close(library) }
+ var filesystem = statfs()
+ guard fstatfs(library, &filesystem) == 0 else {
+ throw VPhoneLaunchpadHelperError("Unable to determine the VM library's volume.")
+ }
+ let mountPoint = withUnsafePointer(to: &filesystem.f_mntonname) {
+ $0.withMemoryRebound(to: CChar.self, capacity: Int(MAXPATHLEN)) { String(cString: $0) }
+ }
+ guard mountPoint.hasPrefix("/Volumes/"), mountPoint != "/Volumes" else {
+ return defaultWorkParent
+ }
+
+ let volume = try VPhoneLaunchpadHelperLibraryPath.openDirectory(mountPoint)
+ defer { close(volume) }
+ var volumeInfo = stat()
+ guard fstat(volume, &volumeInfo) == 0, volumeInfo.st_uid == 0 else {
+ throw VPhoneLaunchpadHelperError("The external volume root must be owned by root before CFW can use it for temporary files.")
+ }
+ guard try !callerCanWrite(volumeInfo, callerUID: callerUID, callerGID: callerGID) else {
+ throw VPhoneLaunchpadHelperError("The external volume root is writable by your account; refusing to place privileged CFW temporary files there.")
+ }
+
+ let leaf = ".vphone-cfw-work"
+ if mkdirat(volume, leaf, 0o700) != 0, errno != EEXIST {
+ throw VPhoneLaunchpadHelperError("Unable to create the CFW work directory on \(mountPoint): \(String(cString: strerror(errno)))")
+ }
+ let work = openat(volume, leaf, O_RDONLY | O_DIRECTORY | O_NOFOLLOW | O_CLOEXEC)
+ guard work >= 0 else {
+ throw VPhoneLaunchpadHelperError("The CFW work directory on \(mountPoint) is not a real directory.")
+ }
+ defer { close(work) }
+ var workInfo = stat()
+ guard fstat(work, &workInfo) == 0,
+ workInfo.st_uid == 0,
+ (workInfo.st_mode & S_IFMT) == S_IFDIR,
+ (workInfo.st_mode & 0o077) == 0
+ else {
+ throw VPhoneLaunchpadHelperError("\(mountPoint)/\(leaf) must be a root-owned private directory.")
+ }
+ return mountPoint + "/" + leaf
+ }
+
+ private static func callerCanWrite(
+ _ directory: stat,
+ callerUID: uid_t,
+ callerGID: gid_t,
+ ) throws -> Bool {
+ let mode = directory.st_mode & 0o777
+ if callerUID == directory.st_uid {
+ return mode & 0o200 != 0
+ }
+ guard let account = getpwuid(callerUID) else {
+ throw VPhoneLaunchpadHelperError("Unable to find the user account for the CFW request.")
+ }
+ var groups = [Int32](repeating: 0, count: 256)
+ var count = Int32(groups.count)
+ let found = String(cString: account.pointee.pw_name).withCString {
+ getgrouplist($0, Int32(callerGID), &groups, &count)
+ }
+ guard found >= 0 else {
+ throw VPhoneLaunchpadHelperError("Unable to check permissions on the external volume root.")
+ }
+ if groups.prefix(Int(count)).contains(Int32(directory.st_gid)) {
+ return mode & 0o020 != 0
+ }
+ return mode & 0o002 != 0
+ }
+
/// The machine a cancel names. It checks no ownership: the operation
/// found under the key is stopped only for the user who started it.
static func machineKey(libraryRoot: String, machineName: String) throws -> MachineKey {
diff --git a/VPhoneLaunchpad/VPhoneLaunchpadShared/VPhoneLaunchpadBundleStore.swift b/VPhoneLaunchpad/VPhoneLaunchpadShared/VPhoneLaunchpadBundleStore.swift
index 21d9b19f..6cf39c97 100644
--- a/VPhoneLaunchpad/VPhoneLaunchpadShared/VPhoneLaunchpadBundleStore.swift
+++ b/VPhoneLaunchpad/VPhoneLaunchpadShared/VPhoneLaunchpadBundleStore.swift
@@ -80,8 +80,9 @@ nonisolated enum VPhoneLaunchpadNames {
/// `vm config --unlock-at-startup`, which a machine's Settings pass. 2.7.0
/// added `vm clone --new-identity`, which Clone passes, and
/// `vm snapshot`, which the Snapshots sheet runs. 2.8.0 added `vm config
- /// --sync-host-location`, which a machine's Settings pass.
- private static let minimumBundleComponents = (2, 8, 0)
+ /// --sync-host-location`, which a machine's Settings pass. 2.9.0 adds the
+ /// helper-passed `cfw install --work-parent` argument.
+ private static let minimumBundleComponents = (2, 9, 0)
static let minimumBundleVersion =
"\(minimumBundleComponents.0).\(minimumBundleComponents.1).\(minimumBundleComponents.2)"