docs/LINUX.md

   1 # FriiDump on Linux
   2
   3 ## Candidate21 status
   4
   5 FriiDump builds natively with GCC/CMake and uses Linux optical-drive packet
   6 commands through the existing `dvd_drive` transport. Candidate21 makes the
   7 Linux privilege boundary explicit and reproducible.
   8
   9 Candidate21 also corrects the Linux GDR-8050L software tray cycle. Linux may
  10 lock an optical door while the device is open (`CDO_LOCK`). Before each required
  11 Xbox media cycle, FriiDump now releases that lock with `CDROM_LOCKDOOR`, sends
  12 the software eject/load sequence, waits for readiness, and restores the door
  13 lock after a successful load. On a cycle failure it deliberately leaves the
  14 door unlocked so the disc can be recovered without power-cycling the external
  15 drive.
  16
  17 The Linux workflow uses two separate permissions:
  18
  19 1. **Device-node access** — the normal user must be able to open `/dev/sr*` and,
  20    where applicable, the corresponding `/dev/sg*`. On Ubuntu this normally
  21    comes from membership in the `cdrom` group.
  22 2. **Vendor-command authorization** — GameCube/Wii memory-dump methods and Xbox
  23    vendor-unlock paths issue commands outside Linux's ordinary unprivileged
  24    SCSI allowlist. Those operations require effective `CAP_SYS_RAWIO`.
  25
  26 Membership in `cdrom` is necessary but does not replace `CAP_SYS_RAWIO`.
  27
  28 ## Candidate21 DMI and media-ID boundary
  29
  30 Candidate20 proved the Linux SG_IO handshake and XDVDFS data path but left the
  31 media ID empty because its standard READ DVD STRUCTURE helper wrote Format to
  32 CDB byte 11. Candidate21 uses byte 7, matching the copied Windows
  33 `GetMediaID()` request. Live runs log `[XBOX-DVD-STRUCTURE]` PFI and DMI capture
  34 results. The expected Red Faction II media ID is `TQ00501A`.
  35
  36 The step-9 sticky-descrambling transport result remains visible. Final READ
  37 CAPACITY and readable XDVDFS data are authoritative for game-view success.
  38
  39
  40 ## Build
  41
  42 ```bash
  43 cmake -S . -B build \
  44   -DBUILD_STATIC_BINARY=ON \
  45   -DBUILD_NATIVE_REPORT_TESTS=ON \
  46   -DFRIIDUMP_BUILD_COMMIT="$(git rev-parse HEAD)"
  47 cmake --build build --parallel
  48 ./build/src/friidump-xbox-portable-metadata-test
  49 ./build/src/friidump-linux-rawio-test
  50 ./build/src/friidump --help
  51 ```
  52
  53 Linux configuration and the Candidate21 build validator print a warning that a
  54 normal build does **not** install file capabilities. This is intentional: a
  55 compiler invocation must not silently elevate its output or invoke `sudo`.
  56
  57 ## Install the minimum raw-I/O authority
  58
  59 Do not run FriiDump itself with `sudo`, and do not install it setuid-root. Grant
  60 only `CAP_SYS_RAWIO` to the exact validated executable:
  61
  62 ```bash
  63 BIN="$(readlink -f ./build/src/friidump)"
  64 sudo setcap cap_sys_rawio=ep "$BIN"
  65 getcap "$BIN"
  66 ```
  67
  68 Expected output:
  69
  70 ```text
  71 /path/to/friidump cap_sys_rawio=ep
  72 ```
  73
  74 The maintained helper performs identity checks, applies the capability, verifies
  75 that the executable bytes did not change, and confirms the resulting xattr:
  76
  77 ```bash
  78 bash ./validation/friidump-linux-rawio-capability.sh install \
  79   ./build/src/friidump
  80 ```
  81
  82 Status and removal operations are also available:
  83
  84 ```bash
  85 bash ./validation/friidump-linux-rawio-capability.sh status \
  86   ./build/src/friidump
  87
  88 bash ./validation/friidump-linux-rawio-capability.sh remove \
  89   ./build/src/friidump
  90 ```
  91
  92 The maintained release helper applies the capability only to the exact
  93 validated executable:
  94
  95 ```bash
  96 bash ./validation/friidump-linux-rawio-capability.sh \
  97   install ./build/src/friidump
  98 ```
  99
 100 ### Capability lifetime
 101
 102 Linux file capabilities are extended attributes. They are not reliably
 103 preserved by ZIP extraction, ordinary copying, source packaging, or rebuilding.
 104 Replacing or relinking the executable clears the capability. Reapply and verify
 105 `cap_sys_rawio=ep` after every build that will be used for vendor-command
 106 hardware work.
 107
 108 Never assume that a newer candidate inherited the capability from an older
 109 binary. Candidate11 worked because its exact executable carried
 110 `cap_sys_rawio=ep`; Candidate12 and Candidate13 initially did not.
 111
 112 ## Runtime preflight
 113
 114 Before a vendor-command path begins seed retrieval or Xbox unlock, Candidate21
 115 checks the process's effective capability mask from `/proc/self/status`.
 116
 117 With the least-privilege configuration it prints:
 118
 119 ```text
 120 Linux raw-I/O preflight: PASS (CAP_SYS_RAWIO effective; ...).
 121 ```
 122
 123 When the capability is absent, FriiDump refuses the vendor operation before
 124 seed retrieval, prints exact `setcap` and `getcap` commands for the running
 125 executable, writes the failure into the native report, and issues STOP UNIT.
 126 This replaces the previous generic transport-level `EPERM` failure.
 127
 128 Candidate21 also refuses vendor-command work when the entire process is running
 129 as root. Run it as the normal user with the file capability instead.
 130
 131 Standard readable-DVD operations that do not use vendor memory-dump or unlock
 132 commands do not require `CAP_SYS_RAWIO`.
 133
 134 ## Device access
 135
 136 Identify the actual optical device dynamically. Do not assume the external
 137 validation drive is `/dev/sr0`:
 138
 139 ```bash
 140 for dev in /sys/class/block/sr*; do
 141   printf '%s: ' "/dev/${dev##*/}"
 142   xargs < "$dev/device/vendor"
 143   xargs < "$dev/device/model"
 144   xargs < "$dev/device/rev"
 145 done
 146 ```
 147
 148 Inspect permissions for the selected block and SCSI-generic device:
 149
 150 ```bash
 151 id
 152 ls -l /dev/sr1 /dev/sg2
 153 getcap "$(readlink -f ./build/src/friidump)"
 154 ```
 155
 156 Close media players and file managers, unmount any mounted filesystem from the
 157 drive, and disable automatic media polling where practical. Linux currently
 158 provides no FriiDump-exclusive optical-volume lock equivalent for this path.
 159
 160 ## Xbox XISO
 161
 162 ```bash
 163 ./build/src/friidump \
 164   -d /dev/sr1 \
 165   -T 4 \
 166   -X "Red Faction II [TQ00501A].xiso" \
 167   --firmware-modified \
 168     "GDR-8163B cross-flashed with modified GDR-8050L firmware; patched to allow 0xE7 memory dumps"
 169 ```
 170
 171 Omitting the XISO filename on a GDR-8050L derives `Title[MediaID].xiso` from the
 172 unlocked XBE/DMI view on Linux.
 173
 174 ## Xbox redump-style ISO
 175
 176 ```bash
 177 ./build/src/friidump \
 178   -d /dev/sr1 \
 179   -T 4 \
 180   -i "Red Faction II [TQ00501A].iso" \
 181   --firmware-modified \
 182     "GDR-8163B cross-flashed with modified GDR-8050L firmware; patched to allow 0xE7 memory dumps"
 183 ```
 184
 185 ## Validation boundary
 186
 187 A Linux build is not considered ready for vendor-command hardware validation
 188 until all of these are recorded:
 189
 190 - exact executable SHA-256;
 191 - `getcap` output proving `cap_sys_rawio=ep` on that executable;
 192 - normal-user process identity;
 193 - device-node access through the intended group or ACL;
 194 - runtime raw-I/O preflight PASS;
 195 - hardware result, native report, and STOP UNIT result.
 196
 197 The `--xgd1-layout-probe` and `--xgd1-raw-id-probe` development probes remain
 198 Windows-only in this candidate. Their Linux transport port is tracked
 199 separately from ordinary ISO/XISO user-path parity.
 200
 201 ## Candidate21 GDR-8050L Windows-sequence parity
 202
 203 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.
 204
 205 `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.
 206
 207
 208 ## GDR-8050L Xbox handshake transport
 209
 210 Candidate21 keeps the proven Windows `UnlockDrive()` command sequence but sends
 211 its Linux form with `SG_IO`, the direct Linux SCSI pass-through interface. This
 212 preserves each 6-, 10-, and 12-byte CDB length, the Windows 120-second command
 213 timeouts, the 10-second sticky-descrambling timeout, transfer direction, sense
 214 data, host status, and driver status. Every handshake command emits an
 215 `[XBOX-SGIO]` record to both the live console and persistent FriiDump log.
 216
 217 This is transport parity only. It does not add `RecoveryKick`, a generic media
 218 authentication kick, synthetic LBA-zero reads, or any modified-firmware-only
 219 recovery behavior.