Zum Inhalt springen
Wirklich letzter Blog

Wirklich letzter Blog

Anleitungen und Notizen zu Homelab, Linux und Netzwerk.

Neueste Beiträge

Forgejo Runner für Mac und Windows

Pascal Knoll

macOS unter Alpine Linux mit QEMU/KVM betreiben

Eine Alpine-VM kann als Host für eine weitere virtuelle Maschine dienen. Damit lässt sich beispielsweise eine macOS-Umgebung für Software-Builds auf einem vorhandenen Linux-Server bereitstellen. Alpine benötigt dafür keinen Desktop: QEMU stellt den Bildschirm der macOS-VM über VNC bereit, der Zugriff erfolgt durch einen SSH-Tunnel.

Diese Anleitung verwendet Alpine Linux 3.24 auf einem x86_64-System und installiert macOS Tahoe 26 über OSX-KVM. Tahoe ist derzeit die neueste auswählbare Version im Downloadskript dieses Projekts.

Apples macOS-Lizenz beschränkt die Nutzung auf Apple-Hardware. Eine Installation auf einem gewöhnlichen Intel- oder AMD-Server entspricht diesen Lizenzbedingungen nicht. Die Bedingungen zur Virtualisierung stehen in der macOS-Lizenzvereinbarung.

Für die folgende Konfiguration werden benötigt:

  • Eine Alpine-VM mit x86_64-Architektur.
  • Durchgereichte Hardware-Virtualisierung und AVX2-Unterstützung.
  • Ein verfügbares KVM-Gerät unter /dev/kvm.
  • Empfohlen: mindestens 16 GB RAM für Alpine, davon 8 GB für macOS.
  • Ausreichend Speicher auf einer SSD für einen virtuellen Datenträger mit 128 GB.
  • Ein Arbeitsplatzrechner mit SSH und einem VNC-Client.

Die macOS-VM wird zunächst mit einem virtuellen CPU-Kern betrieben. Das ist für Builds langsam, vereinfacht aber die Fehlersuche bei verschachtelter Virtualisierung. In der hier beschriebenen Umgebung stürzte macOS mit mehreren virtuellen Kernen wiederholt ab; mit einem Kern lief der Start weiter. Die genaue Ursache war damit noch nicht nachgewiesen.

Alle folgenden Serverbefehle werden innerhalb der Alpine-VM als root ausgeführt.

Wenn Alpine selbst virtualisiert ist, muss bereits der äußere Hypervisor Nested Virtualization erlauben und die benötigten CPU-Funktionen durchreichen.

Terminal-Fenster
(
set -eu
cat /etc/alpine-release
uname -m
[ "$(uname -m)" = x86_64 ] || {
echo "Diese Konfiguration benötigt einen x86_64-Host."
exit 1
}
if grep -qw vmx /proc/cpuinfo; then
modprobe kvm_intel
elif grep -qw svm /proc/cpuinfo; then
modprobe kvm_amd
else
echo "Hardware-Virtualisierung wird nicht durchgereicht."
exit 1
fi
[ -c /dev/kvm ] || {
echo "/dev/kvm fehlt."
exit 1
}
grep -qw avx2 /proc/cpuinfo || {
echo "AVX2 wird nicht bereitgestellt."
exit 1
}
ls -l /dev/kvm
free -m
echo "KVM-Gerät und benötigte CPU-Flags sind vorhanden."
)

Fehlen vmx, svm oder /dev/kvm, muss die Konfiguration des äußeren Hypervisors geprüft werden. Die Installation von QEMU innerhalb von Alpine ersetzt diese Voraussetzung nicht.

Die benötigten QEMU-Pakete liegen im Alpine-Repository community. Der folgende Block ergänzt dieses bei Bedarf passend zum bereits eingetragenen main-Repository.

Terminal-Fenster
(
set -eu
community_repo=$(awk '
$0 !~ /^[[:space:]]*#/ && /\/main\/?$/ {
sub(/\/main\/?$/, "/community")
print
exit
}
' /etc/apk/repositories)
[ -n "$community_repo" ] || {
echo "Kein main-Repository in /etc/apk/repositories gefunden."
exit 1
}
if ! grep -Fxq "$community_repo" /etc/apk/repositories; then
printf '\n%s\n' "$community_repo" >> /etc/apk/repositories
fi
apk update
apk add \
bash git python3 ca-certificates tmux \
qemu-system-x86_64 qemu-img qemu-block-dmg-bz2
qemu-system-x86_64 --version
)

Eine zusätzliche Installation von libvirt oder einer grafischen Verwaltungsoberfläche ist für diesen Aufbau nicht erforderlich.

OSX-KVM enthält den OpenCore-Bootloader, die benötigte Firmware und ein Werkzeug zum Herunterladen des Apple-Recovery-Images.

Der folgende Block ist für die einmalige Vorbereitung einer neuen VM gedacht:

Terminal-Fenster
(
set -eu
mkdir -p "$HOME/vms"
cd "$HOME/vms"
git clone --depth 1 --recursive \
https://github.com/kholia/OSX-KVM.git macos-tahoe
cd macos-tahoe
python3 fetch-macOS-v2.py --shortname tahoe
qemu-img convert -p -f dmg -O raw \
BaseSystem.dmg BaseSystem.img
qemu-img create -f qcow2 mac_hdd_ng.img 128G
)

qemu-img wandelt das Recovery-Image direkt in das benötigte RAW-Format um. Der virtuelle Datenträger im QCOW2-Format wächst mit seiner Nutzung; die angegebenen 128 GB werden nicht sofort vollständig auf dem Host belegt.

Aus dem mitgelieferten Startskript entsteht eine eigene Variante mit folgenden Einstellungen:

Einstellung Wert
Arbeitsspeicher 8 GB
Virtuelle CPU-Kerne 1
VNC 127.0.0.1:5901
Weiterleitung zum macOS-SSH-Port 127.0.0.1:22222

VNC und die SSH-Weiterleitung lauschen ausschließlich auf der Loopback-Adresse der Alpine-VM.

Terminal-Fenster
(
set -eu
cd "$HOME/vms/macos-tahoe"
python3 - <<'PY'
from pathlib import Path
import re
text = Path("OpenCore-Boot.sh").read_text()
assert "-cpu Skylake-Client" in text, (
"Das Upstream-Skript hat sich geändert. CPU-Konfiguration prüfen."
)
for name, value in [
("ALLOCATED_RAM", "8192"),
("CPU_SOCKETS", "1"),
("CPU_CORES", "1"),
("CPU_THREADS", "1"),
]:
text, count = re.subn(
rf"^{name}=.*$",
f'{name}="{value}"',
text,
flags=re.M,
)
assert count == 1, f"Konfiguration nicht eindeutig gefunden: {name}"
replacements = {
"hostfwd=tcp::2222-:22":
"hostfwd=tcp:127.0.0.1:22222-:22",
'qemu-system-x86_64 "${args[@]}"':
'exec qemu-system-x86_64 "${args[@]}" '
'-display none -vnc 127.0.0.1:1',
}
for before, after in replacements.items():
assert text.count(before) == 1, (
f"Das Upstream-Skript hat sich geändert: {before}"
)
text = text.replace(before, after, 1)
script = Path("start-macos.sh")
script.write_text(text)
script.chmod(0o755)
PY
bash -n start-macos.sh
)

Die Prüfungen verhindern, dass Änderungen am Upstream-Skript unbemerkt zu einem unvollständig angepassten Launcher führen.

Hat Alpine insgesamt nur 8 GB RAM, muss die Speicherzuweisung für macOS niedriger ausfallen:

Terminal-Fenster
sed -i \
's/^ALLOCATED_RAM=.*/ALLOCATED_RAM="4096"/' \
"$HOME/vms/macos-tahoe/start-macos.sh"

Für größere Rust-Builds ist diese kleinere Konfiguration allerdings knapp bemessen.

Ein kleiner Launcher lädt das passende KVM-Modul und setzt die von OSX-KVM verwendete Einstellung ignore_msrs.

cat > "$HOME/vms/macos-tahoe/run-macos.sh" <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
cd "$(dirname "$0")"
if grep -qw vmx /proc/cpuinfo; then
modprobe kvm_intel
elif grep -qw svm /proc/cpuinfo; then
modprobe kvm_amd
else
echo "Hardware-Virtualisierung ist nicht verfügbar."
exit 1
fi
test -c /dev/kvm
printf '1\n' > /sys/module/kvm/parameters/ignore_msrs
exec bash ./start-macos.sh
EOF
chmod +x "$HOME/vms/macos-tahoe/run-macos.sh"

Die Einstellung gilt für das KVM-Modul der Alpine-VM und damit auch für andere dort betriebene KVM-Gäste.

Anschließend wird QEMU in tmux gestartet:

Terminal-Fenster
cd "$HOME/vms/macos-tahoe"
tmux new-session -s macos-tahoe './run-macos.sh'

Im Terminal erscheint der QEMU-Monitor. Mit Strg+B, anschließend D wird die tmux-Sitzung verlassen, während die VM weiterläuft.

Zurück zur Sitzung geht es mit:

Terminal-Fenster
tmux attach -t macos-tahoe

Der Monitorbefehl quit beendet QEMU und damit die VM. Er dient nicht zum Verlassen der tmux-Sitzung.

SSH-Tunnel für VNC erlauben

Der Zugriff auf VNC erfolgt über SSH. Falls der SSH-Server TCP-Weiterleitungen untersagt, meldet der Client:

channel 2: open failed: administratively prohibited: open failed

Für einen SSH-Benutzer namens alpine kann am Ende von /etc/ssh/sshd_config eine passende Regel eingetragen werden:

Match User alpine
DisableForwarding no
AllowTcpForwarding local
PermitOpen 127.0.0.1:5901 127.0.0.1:22222
Match all

Existiert bereits ein passender Match-Abschnitt, sollte dieser angepasst werden. Frühere übereinstimmende Regeln können Vorrang haben. Die verwendeten Optionen sind in der OpenSSH-Dokumentation beschrieben.

Vor dem Bearbeiten eine Sicherung erstellen und die bestehende SSH-Sitzung geöffnet lassen:

Terminal-Fenster
cp -p /etc/ssh/sshd_config \
"/etc/ssh/sshd_config.backup.$(date +%s)"

Nach der Änderung die Konfiguration prüfen und neu laden:

Terminal-Fenster
sshd -t && rc-service sshd reload

Für den Tunnel muss anschließend eine neue SSH-Verbindung aufgebaut werden.

Auf einem Arch-Linux-Arbeitsplatz lässt sich TigerVNC installieren:

Terminal-Fenster
sudo pacman -Syu --needed tigervnc

Danach den Tunnel zur Alpine-VM öffnen. Benutzer, Schlüsselpfad und Serveradresse entsprechend ersetzen:

Terminal-Fenster
ssh -i ~/.ssh/MEIN_SSH_SCHLUESSEL \
-N -o ExitOnForwardFailure=yes \
-L 127.0.0.1:5901:127.0.0.1:5901 \
-L 127.0.0.1:22222:127.0.0.1:22222 \
alpine@ALPINE_IP

Dieses Terminal bleibt geöffnet. In einem zweiten Terminal wird der Viewer gestartet:

Terminal-Fenster
vncviewer 127.0.0.1::5901

Bei TigerVNC kennzeichnet der doppelte Doppelpunkt eine ausdrückliche Portnummer.

Die Verbindung führt vom Arbeitsplatz durch den SSH-Tunnel zum QEMU-VNC-Server auf Alpine. Dieser zeigt den Bildschirm der macOS-VM an. Eine Desktop-Umgebung auf Alpine ist dafür nicht notwendig.

Im OpenCore-Menü zunächst macOS Base System auswählen.

Im Recovery-System:

  1. Das Festplattendienstprogramm öffnen.

  2. Unter Darstellung → Alle Geräte einblenden die vollständige Geräteansicht aktivieren.

  3. Den virtuellen 128-GB-Datenträger auswählen.

  4. Den Datenträger mit folgenden Einstellungen löschen:

    • Name: Macintosh HD
    • Format: APFS
    • Schema: GUID-Partitionstabelle
  5. Das Festplattendienstprogramm schließen.

  6. Die macOS-Installation auf Macintosh HD starten.

Während der Installation erfolgen mehrere Neustarts. OpenCore muss dabei je nach Installationsphase den Eintrag macOS Installer beziehungsweise später Macintosh HD starten.

Die Meldung „Dein Computer wurde aufgrund eines Problems neu gestartet“ weist dagegen auf einen Absturz hin. Sie sollte nicht als gewöhnlicher Installationsneustart eingeordnet werden.

Nach der Installation unter Systemeinstellungen → Allgemein → Freigaben → Entfernte Anmeldung den SSH-Zugang aktivieren.

Bei geöffnetem Tunnel ist macOS anschließend vom Arbeitsplatz aus erreichbar:

Terminal-Fenster
ssh -p 22222 MACOS_BENUTZER@127.0.0.1

Für spätere Desktop-Builds lassen sich innerhalb von macOS die Xcode Command Line Tools installieren:

Terminal-Fenster
xcode-select --install

Die weiteren Build-Werkzeuge wie Node.js und Rust werden ebenfalls innerhalb der macOS-VM installiert.

Wenn tmux unmittelbar [exited] meldet, ist der darin gestartete Prozess beendet worden. Ein direkter Start macht die Fehlermeldung sichtbar:

Terminal-Fenster
cd "$HOME/vms/macos-tahoe"
bash ./run-macos.sh 2>&1 | tee /tmp/macos-tahoe-start.log

Ob QEMU und der VNC-Server laufen, lässt sich unabhängig davon prüfen:

Terminal-Fenster
ps w | grep '[q]emu-system'
netstat -lntp | grep ':5901'

Im QEMU-Monitor liefern diese Befehle den aktuellen Zustand und die konfigurierten CPUs:

info status
info cpus

Bei dieser Konfiguration sollte nur CPU #0 erscheinen. VM status: running bestätigt, dass die virtuelle Maschine ausgeführt wird; es bestätigt noch keinen erfolgreichen macOS-Start.

Bei dieser Meldung kann QEMU den angeforderten Gast-RAM nicht bereitstellen:

cannot set up guest memory 'pc.ram': Out of memory

Die Alpine-VM benötigt Speicher für ihr eigenes System und gegebenenfalls weitere Dienste. Der Gast-RAM darf deshalb nicht den gesamten verfügbaren Arbeitsspeicher beanspruchen.

Schlägt das Anlegen einer Weiterleitung fehl, zunächst die Belegung prüfen:

Terminal-Fenster
netstat -lntp | grep -E ':(5901|22222)[[:space:]]'

Ein weiterer QEMU-Prozess oder ein anderer Dienst kann den Port bereits verwenden. Vor einem zweiten Start sollte außerdem geprüft werden, ob die bestehende VM noch läuft.

Eine Warnung wie diese zeigt, dass das angeforderte CPU-Merkmal nicht bereitgestellt wird:

host doesn't support requested feature:
CPUID[eax=80000007h].EDX.invtsc

Mit der hier verwendeten CPU-Prüfung ist diese Warnung allein kein Abbruchgrund. Entscheidend sind der weitere Bootverlauf und mögliche Panic-Meldungen im VNC-Fenster.

Bei wiederholten Abstürzen in einer verschachtelten VM sollten CPU-Durchreichung und Zeitgeber des äußeren Hypervisors untersucht werden. Ein erfolgreicher Start mit einem Kern liefert dafür einen Hinweis, ersetzt aber keine Diagnose der eigentlichen Absturzursache.

Nach einem Neustart von Alpine wird die vorhandene VM erneut über den Launcher gestartet:

Terminal-Fenster
cd "$HOME/vms/macos-tahoe"
tmux new-session -s macos-tahoe './run-macos.sh'

Die Vorbereitung und die Erstellung des virtuellen Datenträgers werden nicht wiederholt.

Zum Herunterfahren zunächst die entsprechende Funktion in macOS verwenden. Sobald das Gastsystem heruntergefahren ist, kann QEMU bei Bedarf im Monitor mit quit beendet werden.