ps5-linux-image/README.md

# PS5 Linux Image Builder

Builds bootable Linux USB images for PlayStation 5 using Docker containers. Supports Ubuntu 26.04, Arch, CachyOS (Gamescope + Steam), and full Kali Linux, individually or as a multi-distro image with kexec switching.

## Prerequisites

- Docker (with permission to run `--privileged` containers) — install as per your distro's instructions
- ~30GB free disk space for Ubuntu, Arch, or CachyOS; a full Kali build needs
  substantial working space because it creates a 96GB image and a full rootfs
  tree (`~150GB` free recommended for a clean Kali build)

Once Docker is installed, add your user to the docker group and apply it without logging out:

```bash
sudo usermod -aG docker $USER
newgrp docker
```

## Quick Start

```bash
# Build a single Ubuntu 26.04 image
./build_image.sh --distro ubuntu2604

OR

# Build CachyOS (Arch-based, Gamescope + Steam Big Picture)
./build_image.sh --distro cachyos

OR

# Build Kali Linux (XFCE + kali-linux-everything)
./build_image.sh --distro kali

OR

# Build a multi-distro image (ubuntu2604 + arch + cachyos)
./build_image.sh --distro all
```

The script auto-clones the kernel source, applies PS5 patches, compiles, and builds the image. Subsequent runs reuse cached artifacts automatically. Press Ctrl+C at any time to abort cleanly.

## Flash to USB

```bash
sudo dd if=output/ps5-ubuntu2604.img of=/dev/sdX bs=4M status=progress
```

## Kali First Boot Time Sync

The Kali image uses UTC by default and enables `ntpsec`. PS5 hardware may boot
Linux without a correct real-time clock, so the displayed time can be wrong
until a network connection is available. The Kali recipe configures IPv4 NTP
sources that were validated through Android USB tethering, because that
connection may not provide usable IPv6 routing.

The Xfce clock's **Time and Date** window is the legacy `time-admin` utility.
On Kali it can report that NTP support is not installed even though `ntpsec`
is installed and active. Verify or repair synchronization from a terminal:

```bash
systemctl --no-pager status ntpsec
ntpq -pn
timedatectl status
```

If the PS5 clock is still wrong after the internet connection is active, force
one initial correction and restart continuous synchronization:

```bash
sudo systemctl stop ntpsec
sudo ntpd -gq -c /etc/ntpsec/ntp.conf
sudo systemctl start ntpsec
date
```

To use a local timezone after boot, for example Kentucky:

```bash
sudo timedatectl set-timezone America/Kentucky/Louisville
timedatectl status
```

## Kali Internal WiFi

The Kali image builds and installs the PS5 IW620 `mwifiex` modules for the
PS5-patched kernel. On boot, `ps5-iw620.service` copies the console-specific
firmware dumped by `ps5-linux-loader` from `/boot/efi/lib/nxp/` into
`/lib/firmware/nxp/`, loads the driver, and enables WiFi radio. If the firmware
payload is present, NetworkManager should expose the internal interface as
`mlan0` and the Xfce network applet can be used to scan and connect.

The Kali desktop autologin is enabled for local first boot. SSH is installed
but disabled by default because the initial local account is `kali` with
password `kali`. Before enabling remote access, change that password:

```bash
passwd
sudo systemctl enable --now ssh
```

The image holds its installed kernel packages and protects the boot-copy hook
from deploying a generic Kali kernel. Do not replace or unhold the PS5 kernel
unless you are intentionally testing a new PS5-patched kernel build.

Ghidra is configured to use JDK 21, its documented supported runtime. Full
Kali installations may also contain newer Java versions for other software.

`kali-linux-everything` installs NFS client components, but the PS5-patched
kernel has NFS disabled. A failed `run-rpc_pipefs.mount` unit can therefore be
reported at boot; it only indicates that NFS mounts are unavailable. The Kali
desktop and security tools are unaffected.

The full Kali toolset also enables `chkrootkit.timer`; its daily integrity scan
can use noticeable CPU time while it runs.

## Options

| Flag | Description | Default |
|------|-------------|---------|
| `--distro` | `ubuntu2604`, `arch`, `cachyos`, `kali`, or `all` | `ubuntu2604` |
| `--kernel` | Path to kernel source directory | auto-clone version selected by PS5 patch set |
| `--img-size` | Disk image size in MB | `12000` (`32000` for `all`, `98304` for `kali`) |
| `--clean` | Remove all cached build artifacts and start fresh | off |
| `--kernel-only` | Build and package the kernel only, then exit | off |
| `--patches-ref` | Branch, tag, or commit SHA for patches | `v1.2` |

## Caching

The build automatically skips stages that have already completed:

- **Kernel source** — reused if `work/linux/` exists
- **Kernel packages** — reused if `.deb`/`.pkg.tar.zst` files exist in `linux-bin/`
- **Root filesystem** — reused if chroot directories are populated

Use `--clean` to wipe everything and rebuild from scratch. The build will also suggest `--clean` if a stage fails.

## Build Output

```
PS5 Linux Image Builder
=======================
  Distro:       all
                (ubuntu2604 arch cachyos)
  Image size:   32000MB
  Kernel src:   /path/to/work/linux

Stages:
  1. Kernel            cached
  2. Root filesystem   build
  3. Disk image        build

Logs: /path/to/build.log

  ✓ Kernel packages (cached)
  ✓ Build image builder image
  ⠹ Building arch rootfs
```

All verbose output goes to `build.log`. The terminal shows a spinner with live progress.

## Distributions

| Distro | Desktop | Kernel format | Init |
|--------|---------|---------------|------|
| Ubuntu 26.04 (Resolute) | GNOME | `.deb` | systemd |
| Arch | Sway | `.pkg.tar.zst` | systemd |
| CachyOS | Gamescope + Steam Big Picture (Arch + `[cachyos]` repo, no v3 migration in image build) | `.pkg.tar.zst` | systemd |
| Kali Linux Rolling | XFCE + `kali-linux-everything` | `.deb` | systemd |

## Multi-distro Image

`--distro all` builds a 32GB image with 4 partitions (one EFI boot partition plus three root filesystems):

| Partition | Type | Label | Content |
|-----------|------|-------|---------|
| p1 | FAT32 | boot | Shared kernel, per-distro initrds, kexec scripts |
| p2 | ext4 | ubuntu2604 | Ubuntu 26.04 rootfs |
| p3 | ext4 | arch | Arch rootfs |
| p4 | ext4 | cachyos | CachyOS rootfs |

The boot partition contains kexec scripts to switch between distros at runtime. Ubuntu 26.04 is the default boot target.

## Building the Kernel Standalone

Use `--kernel-only` to compile the PS5 kernel and produce installable packages without building a full disk image.

```bash
./build_image.sh --kernel-only                                # .deb (default)
./build_image.sh --kernel-only --distro all                   # .deb + .pkg.tar.zst
./build_image.sh --kernel-only --patches-ref main             # fetch from specific branch/tag
./build_image.sh --kernel-only --clean                        # wipe and rebuild from scratch
```

Output packages are written to `linux-bin/`. Install on a running PS5 Linux system:

```bash
sudo dpkg -i linux-bin/linux-ps5_*.deb
```

## Directory Layout

```
build_image.sh                  # Image builder (also supports --kernel-only)
docker/
  kernel-builder/               # Kernel compilation container
  kernel-builder-arch/         # Repackages .deb kernel as .pkg.tar.zst
  image-builder/
    Dockerfile                  # Image building container (distrobuilder)
    entrypoint.sh               # Single-distro build logic
    entrypoint-multi.sh         # Multi-distro build logic
distros/
  ubuntu2604/                   # Ubuntu 26.04 (Resolute)
  arch/                         # Arch Linux
  cachyos/                      # CachyOS repos + Gamescope/Steam
  kali/                         # Kali Linux Rolling
  shared/                       # Kernel postinst hooks (single + multi)
boot/
  cmdline.txt                   # Kernel cmdline template (__DISTRO__ placeholder)
  vram.txt                      # VRAM allocation
  kexec-{ubuntu2604,arch,cachyos}.sh
work/                           # Build artifacts (auto-created)
linux-bin/                      # Compiled kernel packages
output/                         # Final .img files
```