Document exact-release Linux hardware validation

[friidump.git] / README

diff --git a/README b/README
index a481527d4d38da594015dea1f206887da49abb6f..a9f2616dd34ee80e198716bea06ba66c1e40c79d 100644 (file)
--- a/README
+++ b/README
@@ -7,6 +7,16 @@ FF 08 01 vendor lock-state path, redump-style metadata output, optional
 XISO output, and a convenient forced-DVD mode (`-D` / `--dvd`). See
 docs/XBOX.md for Xbox-specific details.
 
 XISO output, and a convenient forced-DVD mode (`-D` / `--dvd`). See
 docs/XBOX.md for Xbox-specific details.
 

+FriiDump 0.5.3.16-pf1 also creates native compatibility evidence reports
+by default for normal dump invocations using the `friidump-test-result.v1`
+contract. The default report is written beside the final FriiDump log and
+derives its filename from that log. `--report-json` overrides the pathname,
+`--report-dir` overrides the destination directory, and
+`--firmware-modified <note>` records modified firmware; omission assumes
+stock firmware. Reports are atomic, preserve exact live drive/firmware
+identity, and distinguish complete, partial, failed, cancelled, diagnostic,
+and resumed runs. See `docs/NATIVE_REPORTS.md`.
+

 FriiDump is a program that lets you dump Nintendo Wii and GameCube disc from
 your computer, without using original Nintendo hardware. It basically performs
 the same functions as the famous "RawDump" program, but with a big difference,
 FriiDump is a program that lets you dump Nintendo Wii and GameCube disc from
 your computer, without using original Nintendo hardware. It basically performs
 the same functions as the famous "RawDump" program, but with a big difference,


@@ -150,23 +160,27 @@ $ cmake ..
 $ make
 $ make install
 
 $ make
 $ make install
 

-Linux-specific note: You need root privileges to issue certain commands to the
-DVD-ROM drive. Hence you have the following possibilities:
-- Run FriiDump as root: discouraged.
-- Run it through sudo: better but nevertheless discouraged.
-- Set the setuid bit on the executable: this is the recommended way to run
-  FriiDump under Linux. This way, the code run with superuser privileges will
-  be reduced to a minimum, guaranteeing a certain level of security (note that
-  security-related bugs might exist anyway!!!). Also note that, even when the
-  setuid bit is set, the attempt to open the drive for reading will be done
-  after privileges have been dropped, so you will need explicit read access to
-  the DVD-ROM drive. Usually having the system administrator add you to the
-  "cdrom" group is enough. To set the setuid bit on the executable, run as
-  root:
+Linux-specific note: Run FriiDump as a normal user. Do not run it with `sudo`,
+and do not install it setuid-root.
+
+Linux vendor-command paths need two separate permissions:
+
+- The normal user needs access to the selected `/dev/sr*` device and, when
+  applicable, its `/dev/sg*` device. On Ubuntu, membership in the `cdrom` group
+  normally provides this access.
+- GameCube/Wii memory-dump methods and Xbox vendor-unlock paths need effective
+  `CAP_SYS_RAWIO` on the exact validated FriiDump executable.

 
 

-  $ chown root:root /usr/local/bin/friidump
-  $ chmod u+s /usr/local/bin/friidump
+After you verify the executable, use the maintained helper:

 
 

+  $ bash ./validation/friidump-linux-rawio-capability.sh install \
+      ./build/src/friidump
+  $ getcap ./build/src/friidump
+
+Rebuilding, relinking, copying, replacing, or re-extracting the executable can
+clear its file capability. Verify `cap_sys_rawio=ep` before each
+vendor-command hardware run. See `docs/LINUX.md` for the complete Linux
+permission and hardware procedure.

 
 ===============================================================================
 Usage
 
 ===============================================================================
 Usage


@@ -176,6 +190,11 @@ or a command-prompt under Windows. The basic usage is as follows:
 
 friidump -d <drive> -a
 
 
 friidump -d <drive> -a
 

+A native compatibility report is created automatically for the same run.
+To place it in a different directory:
+
+friidump -d <drive> -a --report-dir reports
+

 For a plain DVD-ROM dump from any readable drive, use `-D` / `--dvd` or the
 numeric equivalent `-T 3`:
 
 For a plain DVD-ROM dump from any readable drive, use `-D` / `--dvd` or the
 numeric equivalent `-T 3`: