Files
runaway/docs/troubleshooting.md
T
ruihan 75f4ec53ab
CI / Bash Syntax Check (push) Successful in 8s
CI / Markdown Lint (push) Failing after 8s
CI / ShellCheck (push) Failing after 1m26s
chore: migrate all URLs to git.jskdjs.cn, drop GitHub-specific distribution
2026-11-09 10:31:11 +08:00

269 lines
5.7 KiB
Markdown

---
layout: default
title: Troubleshooting — runaway
---
# Troubleshooting
## Common Errors
### "Not a known DirStatus"
Volume auto-detection failed.
```
[ERR] Not a known DirStatus
```
**Fix:**
1. Run `diskutil list` to find your Data volume
2. Mount it: `diskutil mount /dev/diskXsY`
3. Re-run runaway
---
### "Full bypass must run from Recovery mode"
```
[ERR] Full bypass must run from Recovery mode.
```
**Cause:** `bypass` creates admin users via dscl, which only works in Recovery.
**Fix:** Boot to Recovery and try again. Or use `suppress` instead from a booted system.
---
### "Needs sudo" errors
Various commands require root:
```
[ERR] Firewall needs sudo: sudo ./runaway firewall
[ERR] Heal needs sudo: sudo ./runaway heal
[ERR] Hardening needs sudo: sudo ./runaway harden
[ERR] Audit needs sudo: sudo ./runaway audit
[ERR] Check needs sudo: sudo ./runaway check
```
**Fix:** Prepend `sudo` to the command.
---
### MDM comes back after reboot
The most common cause is **user-level artifacts** carried over by Migration Assistant.
**Fix from Recovery:**
```bash
sudo ./runaway suppress
```
**Fix from booted system:**
```bash
sudo ./runaway harden
```
If it keeps returning:
```bash
sudo ./runaway persist # auto-heal on every boot
sudo ./runaway monitor # watch for re-enrollment
```
---
### macOS update re-enabled MDM
System updates restore enrollment daemons automatically.
**Fix:**
```bash
sudo ./runaway heal
```
If you ran `persist` before the update, this runs automatically on next boot.
---
### "Profiles status" still shows enrollment
This is **cosmetic**. macOS stores profile state on the read-only SSV (System Sealed Volume).
**Don't trust** `profiles status -v`.
**Trust** `runaway status -d` instead.
---
### FileVault is enabled
Runaway detects FileVault and prompts for the recovery key or volume password.
**Fix:** If automatic unlock fails, unlock the volume manually in Disk Utility first:
1. Go to Disk Utility in Recovery
2. Select the Data volume
3. File → Unlock → Enter password
4. Re-run runaway
---
### iCloud stops working after bypass
The basic `/etc/hosts` block includes `albert.apple.com` (iCloud activation) and `gdmf.apple.com`.
**Fix:** Use `whitelist` instead of the basic block:
```bash
sudo ./runaway whitelist
```
Or manually remove these two lines from `/etc/hosts`:
```
0.0.0.0 albert.apple.com
0.0.0.0 gdmf.apple.com
```
---
### "Not a macOS Data volume"
```
[ERR] Not a macOS Data volume
```
**Cause:** The mounted volume doesn't have the expected structure.
**Fix:** Run `diskutil list` to find the correct Data volume (look for "Data" in the name or the `69414d41-...` role). Mount the right one and retry.
---
### Monitor won't start
**Check:**
1. Is it already running? `sudo ./runaway monitor-status`
2. Permissions: needs root
3. Check logs: `/var/log/runaway-monitor.log`
**Fix:**
```bash
sudo ./runaway monitor-stop
sudo ./runaway monitor
```
---
### Can't download files in Recovery
Recovery mode has no internet by default.
**Fix:**
1. Use a USB drive with runaway copied to it
2. Or connect to Wi-Fi in Recovery (top-right menu → Wi-Fi icon)
---
### "Library not found" error on startup
```
ERROR: Library not found: /path/to/lib/colors.sh
```
**Cause:** Running the source `runaway` script from outside the repo directory.
**Fix:**
- Use the standalone version (`runaway-standalone.sh`) instead
- Or run from the repo root where the `lib/` directory exists
---
### Firewall rules not applying
pf might have existing rules that conflict.
**Fix:**
```bash
sudo ./runaway firewall-off # clear existing rules
sudo ./runaway firewall # re-apply
```
---
### "Device still locks after DFU restore"
A full DFU/IPSW restore doesn't remove ABM assignment — the serial stays in Apple Business Manager.
**Strategy:**
1. After restore, **do not connect to Wi-Fi**
2. Boot to Recovery
3. Run `runaway bypass` before the device ever phones home
4. Run `runaway persist` and `runaway whitelist`
5. Only then connect to the internet
The serial stays in ABM forever — but if the device never connects without protections, it won't re-enroll.
---
### GPG signature verification fails on update
```
[ERR] GPG signature verification failed
```
**Fix:**
1. Make sure you have `gpg` installed
2. Import the signing key: `gpg --keyserver keys.openpgp.org --recv-key <KEY_ID>`
3. Try `sudo ./runaway update` again
4. Or download manually from [GitHub Releases](https://git.jskdjs.cn/ruihan/runaway/releases)
---
## Logging
All commands produce structured logs:
```
[INF] Data volume: /Volumes/Macintosh HD - Data
[ OK] Admin 'apple' created (UID 501)
[WRN] DEP activation record present
[ERR] Firewall needs sudo: sudo ./runaway firewall
[STP] Locating Data volume by APFS role...
[DBG] Checking pfctl availability
```
**Log format:**
| Prefix | Level |
|--------|-------|
| `[INF]` | Info — normal operation |
| `[ OK]` | Success — operation completed |
| `[WRN]` | Warning — non-critical issue |
| `[ERR]` | Error — operation failed |
| `[STP]` | Step — current action |
| `[DBG]` | Debug — verbose only |
Use `--verbose` for debug messages and `--log-file <path>` to save to a file:
```bash
sudo ./runaway heal --verbose --log-file /tmp/runaway.log
```
---
## Diagnostic Commands
Run these to gather information before seeking help:
```bash
# Quick health check
sudo ./runaway doctor
# Full system audit
sudo ./runaway audit
# Generate report
sudo ./runaway report
# Dry-run a bypass
sudo ./runaway demo
```
---
## Getting Help
- [Issues](https://git.jskdjs.cn/ruihan/runaway/issues)
- [Discussions](https://git.jskdjs.cn/ruihan/runaway/discussions)
- [Security Policy](https://git.jskdjs.cn/ruihan/runaway/src/branch/main/SECURITY.md)