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 candidate validator exposes the same installation step:
  93
  94 ```bash
  95 bash ./validation/friidump-v0.5.3.16-pf1-candidate21-linux-live-validation.sh \
  96   capability
  97 ```
  98
  99 ### Capability lifetime
 100
 101 Linux file capabilities are extended attributes. They are not reliably
 102 preserved by ZIP extraction, ordinary copying, source packaging, or rebuilding.
 103 Replacing or relinking the executable clears the capability. Reapply and verify
 104 `cap_sys_rawio=ep` after every build that will be used for vendor-command
 105 hardware work.
 106
 107 Never assume that a newer candidate inherited the capability from an older
 108 binary. Candidate11 worked because its exact executable carried
 109 `cap_sys_rawio=ep`; Candidate12 and Candidate13 initially did not.
 110
 111 ## Runtime preflight
 112
 113 Before a vendor-command path begins seed retrieval or Xbox unlock, Candidate21
 114 checks the process's effective capability mask from `/proc/self/status`.
 115
 116 With the least-privilege configuration it prints:
 117
 118 ```text
 119 Linux raw-I/O preflight: PASS (CAP_SYS_RAWIO effective; ...).
 120 ```
 121
 122 When the capability is absent, FriiDump refuses the vendor operation before
 123 seed retrieval, prints exact `setcap` and `getcap` commands for the running
 124 executable, writes the failure into the native report, and issues STOP UNIT.
 125 This replaces the previous generic transport-level `EPERM` failure.
 126
 127 Candidate21 also refuses vendor-command work when the entire process is running
 128 as root. Run it as the normal user with the file capability instead.
 129
 130 Standard readable-DVD operations that do not use vendor memory-dump or unlock
 131 commands do not require `CAP_SYS_RAWIO`.
 132
 133 ## Device access
 134
 135 Identify the actual optical device dynamically. Do not assume the external
 136 validation drive is `/dev/sr0`:
 137
 138 ```bash
 139 for dev in /sys/class/block/sr*; do
 140   printf '%s: ' "/dev/${dev##*/}"
 141   xargs < "$dev/device/vendor"
 142   xargs < "$dev/device/model"
 143   xargs < "$dev/device/rev"
 144 done
 145 ```
 146
 147 Inspect permissions for the selected block and SCSI-generic device:
 148
 149 ```bash
 150 id
 151 ls -l /dev/sr1 /dev/sg2
 152 getcap "$(readlink -f ./build/src/friidump)"
 153 ```
 154
 155 Close media players and file managers, unmount any mounted filesystem from the
 156 drive, and disable automatic media polling where practical. Linux currently
 157 provides no FriiDump-exclusive optical-volume lock equivalent for this path.
 158
 159 ## Xbox XISO
 160
 161 ```bash
 162 ./build/src/friidump \
 163   -d /dev/sr1 \
 164   -T 4 \
 165   -X "Red Faction II [TQ00501A].xiso" \
 166   --firmware-modified \
 167     "GDR-8163B cross-flashed with modified GDR-8050L firmware; patched to allow 0xE7 memory dumps"
 168 ```
 169
 170 Omitting the XISO filename on a GDR-8050L derives `Title[MediaID].xiso` from the
 171 unlocked XBE/DMI view on Linux.
 172
 173 ## Xbox redump-style ISO
 174
 175 ```bash
 176 ./build/src/friidump \
 177   -d /dev/sr1 \
 178   -T 4 \
 179   -i "Red Faction II [TQ00501A].iso" \
 180   --firmware-modified \
 181     "GDR-8163B cross-flashed with modified GDR-8050L firmware; patched to allow 0xE7 memory dumps"
 182 ```
 183
 184 ## Validation boundary
 185
 186 A Linux build is not considered ready for vendor-command hardware validation
 187 until all of these are recorded:
 188
 189 - exact executable SHA-256;
 190 - `getcap` output proving `cap_sys_rawio=ep` on that executable;
 191 - normal-user process identity;
 192 - device-node access through the intended group or ACL;
 193 - runtime raw-I/O preflight PASS;
 194 - hardware result, native report, and STOP UNIT result.
 195
 196 The `--xgd1-layout-probe` and `--xgd1-raw-id-probe` development probes remain
 197 Windows-only in this candidate. Their Linux transport port is tracked
 198 separately from ordinary ISO/XISO user-path parity.
 199
 200 ## Candidate21 GDR-8050L Windows-sequence parity
 201
 202 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.
 203
 204 `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.
 205
 206
 207 ## GDR-8050L Xbox handshake transport
 208
 209 Candidate21 keeps the proven Windows `UnlockDrive()` command sequence but sends
 210 its Linux form with `SG_IO`, the direct Linux SCSI pass-through interface. This
 211 preserves each 6-, 10-, and 12-byte CDB length, the Windows 120-second command
 212 timeouts, the 10-second sticky-descrambling timeout, transfer direction, sense
 213 data, host status, and driver status. Every handshake command emits an
 214 `[XBOX-SGIO]` record to both the live console and persistent FriiDump log.
 215
 216 This is transport parity only. It does not add `RecoveryKick`, a generic media
 217 authentication kick, synthetic LBA-zero reads, or any modified-firmware-only
 218 recovery behavior.