# FriiDump on Linux

## Candidate21 status

FriiDump builds natively with GCC/CMake and uses Linux optical-drive packet
commands through the existing `dvd_drive` transport. Candidate21 makes the
Linux privilege boundary explicit and reproducible.

Candidate21 also corrects the Linux GDR-8050L software tray cycle. Linux may
lock an optical door while the device is open (`CDO_LOCK`). Before each required
Xbox media cycle, FriiDump now releases that lock with `CDROM_LOCKDOOR`, sends
the software eject/load sequence, waits for readiness, and restores the door
lock after a successful load. On a cycle failure it deliberately leaves the
door unlocked so the disc can be recovered without power-cycling the external
drive.

The Linux workflow uses two separate permissions:

1. **Device-node access** — the normal user must be able to open `/dev/sr*` and,
   where applicable, the corresponding `/dev/sg*`. On Ubuntu this normally
   comes from membership in the `cdrom` group.
2. **Vendor-command authorization** — GameCube/Wii memory-dump methods and Xbox
   vendor-unlock paths issue commands outside Linux's ordinary unprivileged
   SCSI allowlist. Those operations require effective `CAP_SYS_RAWIO`.

Membership in `cdrom` is necessary but does not replace `CAP_SYS_RAWIO`.

## Candidate21 DMI and media-ID boundary

Candidate20 proved the Linux SG_IO handshake and XDVDFS data path but left the
media ID empty because its standard READ DVD STRUCTURE helper wrote Format to
CDB byte 11. Candidate21 uses byte 7, matching the copied Windows
`GetMediaID()` request. Live runs log `[XBOX-DVD-STRUCTURE]` PFI and DMI capture
results. The expected Red Faction II media ID is `TQ00501A`.

The step-9 sticky-descrambling transport result remains visible. Final READ
CAPACITY and readable XDVDFS data are authoritative for game-view success.


## Build

```bash
cmake -S . -B build \
  -DBUILD_STATIC_BINARY=ON \
  -DBUILD_NATIVE_REPORT_TESTS=ON \
  -DFRIIDUMP_BUILD_COMMIT="$(git rev-parse HEAD)"
cmake --build build --parallel
./build/src/friidump-xbox-portable-metadata-test
./build/src/friidump-linux-rawio-test
./build/src/friidump --help
```

Linux configuration and the Candidate21 build validator print a warning that a
normal build does **not** install file capabilities. This is intentional: a
compiler invocation must not silently elevate its output or invoke `sudo`.

## Install the minimum raw-I/O authority

Do not run FriiDump itself with `sudo`, and do not install it setuid-root. Grant
only `CAP_SYS_RAWIO` to the exact validated executable:

```bash
BIN="$(readlink -f ./build/src/friidump)"
sudo setcap cap_sys_rawio=ep "$BIN"
getcap "$BIN"
```

Expected output:

```text
/path/to/friidump cap_sys_rawio=ep
```

The maintained helper performs identity checks, applies the capability, verifies
that the executable bytes did not change, and confirms the resulting xattr:

```bash
bash ./validation/friidump-linux-rawio-capability.sh install \
  ./build/src/friidump
```

Status and removal operations are also available:

```bash
bash ./validation/friidump-linux-rawio-capability.sh status \
  ./build/src/friidump

bash ./validation/friidump-linux-rawio-capability.sh remove \
  ./build/src/friidump
```

The maintained release helper applies the capability only to the exact
validated executable:

```bash
bash ./validation/friidump-linux-rawio-capability.sh \
  install ./build/src/friidump
```

### Capability lifetime

Linux file capabilities are extended attributes. They are not reliably
preserved by ZIP extraction, ordinary copying, source packaging, or rebuilding.
Replacing or relinking the executable clears the capability. Reapply and verify
`cap_sys_rawio=ep` after every build that will be used for vendor-command
hardware work.

Never assume that a newer candidate inherited the capability from an older
binary. Candidate11 worked because its exact executable carried
`cap_sys_rawio=ep`; Candidate12 and Candidate13 initially did not.

## Runtime preflight

Before a vendor-command path begins seed retrieval or Xbox unlock, Candidate21
checks the process's effective capability mask from `/proc/self/status`.

With the least-privilege configuration it prints:

```text
Linux raw-I/O preflight: PASS (CAP_SYS_RAWIO effective; ...).
```

When the capability is absent, FriiDump refuses the vendor operation before
seed retrieval, prints exact `setcap` and `getcap` commands for the running
executable, writes the failure into the native report, and issues STOP UNIT.
This replaces the previous generic transport-level `EPERM` failure.

Candidate21 also refuses vendor-command work when the entire process is running
as root. Run it as the normal user with the file capability instead.

Standard readable-DVD operations that do not use vendor memory-dump or unlock
commands do not require `CAP_SYS_RAWIO`.

## Device access

Identify the actual optical device dynamically. Do not assume the external
validation drive is `/dev/sr0`:

```bash
for dev in /sys/class/block/sr*; do
  printf '%s: ' "/dev/${dev##*/}"
  xargs < "$dev/device/vendor"
  xargs < "$dev/device/model"
  xargs < "$dev/device/rev"
done
```

Inspect permissions for the selected block and SCSI-generic device:

```bash
id
ls -l /dev/sr1 /dev/sg2
getcap "$(readlink -f ./build/src/friidump)"
```

Close media players and file managers, unmount any mounted filesystem from the
drive, and disable automatic media polling where practical. Linux currently
provides no FriiDump-exclusive optical-volume lock equivalent for this path.

## Xbox XISO

```bash
./build/src/friidump \
  -d /dev/sr1 \
  -T 4 \
  -X "Red Faction II [TQ00501A].xiso" \
  --firmware-modified \
    "GDR-8163B cross-flashed with modified GDR-8050L firmware; patched to allow 0xE7 memory dumps"
```

Omitting the XISO filename on a GDR-8050L derives `Title[MediaID].xiso` from the
unlocked XBE/DMI view on Linux.

## Xbox redump-style ISO

```bash
./build/src/friidump \
  -d /dev/sr1 \
  -T 4 \
  -i "Red Faction II [TQ00501A].iso" \
  --firmware-modified \
    "GDR-8163B cross-flashed with modified GDR-8050L firmware; patched to allow 0xE7 memory dumps"
```

## Validation boundary

A Linux build is not considered ready for vendor-command hardware validation
until all of these are recorded:

- exact executable SHA-256;
- `getcap` output proving `cap_sys_rawio=ep` on that executable;
- normal-user process identity;
- device-node access through the intended group or ACL;
- runtime raw-I/O preflight PASS;
- hardware result, native report, and STOP UNIT result.

The `--xgd1-layout-probe` and `--xgd1-raw-id-probe` development probes remain
Windows-only in this candidate. Their Linux transport port is tracked
separately from ordinary ISO/XISO user-path parity.

## Candidate21 GDR-8050L Windows-sequence parity

The portable Linux path follows the proven Windows state-aware order: readiness, entry capacity, direct `UnlockDrive()`, `RefreshVolume()`, a 2000 ms settle, readiness and capacity verification, with exactly one tray-cycle retry only if the direct handshake remains in the video view. It then sets maximum speed and proceeds to metadata. The same helper is used after video capture.

`RecoveryKick`, repeated synthetic LBA-zero reads, and generic automatic media-auth kicks are not part of this path. They belong only to a separate experimental modified-firmware campaign and are currently out of scope.


## GDR-8050L Xbox handshake transport

Candidate21 keeps the proven Windows `UnlockDrive()` command sequence but sends
its Linux form with `SG_IO`, the direct Linux SCSI pass-through interface. This
preserves each 6-, 10-, and 12-byte CDB length, the Windows 120-second command
timeouts, the 10-second sticky-descrambling timeout, transfer direction, sense
data, host status, and driver status. Every handshake command emits an
`[XBOX-SGIO]` record to both the live console and persistent FriiDump log.

This is transport parity only. It does not add `RecoveryKick`, a generic media
authentication kick, synthetic LBA-zero reads, or any modified-firmware-only
recovery behavior.