# PCRT Diagnostics Linux

PCRT Diagnostics Linux is the command-line Linux client for the PCRT Diagnostics platform. It uses the existing PCRT Diagnostics Server session workflow and uploads the same four report files used by the Windows client.

Version: **0.1.0**

Production server:

```text
https://scan.pcrtdiag.com:8443/
```

The server address is compiled into the release client. The normal client only needs the five-character session code.

## Quick start

Use the binary that matches the Linux architecture:

```bash
chmod +x pcrt-diagnostics-linux-amd64
sudo ./pcrt-diagnostics-linux-amd64 --code ABCDE
```

The session code may also be supplied positionally:

```bash
sudo ./pcrt-diagnostics-linux-amd64 ABCDE
```

ARM64 systems use:

```bash
sudo ./pcrt-diagnostics-linux-arm64 --code ABCDE
```

The scanner requires root because physical-drive reads, SMART, DMI, kernel logs, TPM, and some hardware sensors are restricted on Linux.

## Command-line options

```text
-code string
      five-character PCRT session code
-c string
      five-character PCRT session code (shorthand)
-output string
      report output directory (optional)
-verbose
      print detailed diagnostic log messages
-version
      print version and exit
```

Example with a selected local report directory:

```bash
sudo ./pcrt-diagnostics-linux-amd64 \
  --code ABCDE \
  --output /var/tmp/pcrt-test \
  --verbose
```

## Session workflow

The client preserves the current PCRT server behavior:

1. Fetches the unused session configuration without consuming the code.
2. Claims the code using a random client identifier.
3. Receives a server-issued `X-PCRT-Claim-Token`.
4. Sends progress and status updates.
5. Runs the Linux implementation of the selected scan type.
6. Creates the four report files.
7. Uploads the files using the claim token.
8. Completes only after the server returns `acknowledged: true`.

The client works with PCRT Diagnostics Server 0.1.4 and does not require a server schema change.

When `PCRT_REQUIRE_API_TOKEN=true` is enabled on the server, provide its token through the environment:

```bash
sudo env PCRT_API_TOKEN='token-value' ./pcrt-diagnostics-linux-amd64 --code ABCDE
```

## Reports

Every run creates:

- `system-info.html` — Linux, hardware, device, storage, network, and power inventory
- `test-results.html` — technician-facing status, domain results, evidence, and recommendations
- `raw-data.json` — complete structured data and command evidence
- `run-log.txt` — client workflow, server communication warnings, and diagnostic log entries

When `--output` is not supplied, reports are placed in:

```text
/home/<sudo-user>/PCRTDiagnostics/HOSTNAME_YYYY-MM-DD_HH-mm-ss/
```

If a normal sudo user cannot be identified, the fallback location is:

```text
/var/tmp/PCRTDiagnostics/HOSTNAME_YYYY-MM-DD_HH-mm-ss/
```

The client returns report ownership to the invoking sudo user when `SUDO_UID` and `SUDO_GID` are available.

## Scan types

The server continues to select the scan type. The Linux client implements Linux-appropriate coverage for the existing preset names.

### Quick

- Linux and hardware inventory
- CPU deterministic prime calculation
- Memory inventory and application-level patterns
- Storage inventory and filesystem capacity
- SMART/NVMe health when available
- Temporary disk write/read/hash verification
- PCIe, USB, thermal, network, power, services, security, package-update, and kernel-event review

### Full

Quick coverage plus:

- Read-only physical-drive sampling
- Sustained CPU workload
- Sustained memory workload when requested by the server preset
- TPM and RTC status
- GPU/display inventory
- Before/after kernel hardware-event comparison

### Deep

Full coverage with the deeper server-provided CPU, memory, and disk limits.

### Hardware Diagnostic

Focused hardware coverage:

- CPU inventory and known-result calculations
- Sustained CPU workload
- Memory inventory and 512 MB target pattern testing when safely available
- SMART/NVMe health
- Read-only physical-drive sampling
- PCIe and USB inventory/status
- TPM and RTC status
- Temperature sensors
- Kernel hardware-event review

### Drive

Focused storage coverage:

- Physical storage inventory
- SMART/NVMe health
- Read-only physical-drive sampling
- Filesystem capacity and mount state
- Temporary disk write/read/hash verification
- Kernel storage-event review

### Thermal

- Idle temperature sensors
- Sustained CPU workload
- Post-workload temperature sensors
- Kernel hardware-event review

### GPU / Display

- DRM, PCI, and available vendor-tool inventory
- OpenGL driver query when a graphical session and `glxinfo` are available
- Temperature sensors
- Kernel GPU-event review

Version 0.1.0 does not perform a dedicated Linux GPU stress workload. The GPU preset reports that coverage as unavailable when a functional graphical driver query cannot be performed.

### Burn-in

Full automated Linux diagnostics plus server-configured sustained CPU, memory, and disk workloads and a post-workload kernel-event comparison.

## Optional diagnostic packages

The core client is a self-contained binary and requires no runtime packages. Additional Linux tools improve coverage when installed.

Debian and Ubuntu:

```bash
sudo apt install smartmontools dmidecode pciutils usbutils lm-sensors tpm2-tools mokutil mesa-utils
```

Fedora, RHEL, and compatible distributions:

```bash
sudo dnf install smartmontools dmidecode pciutils usbutils lm_sensors tpm2-tools mokutil glx-utils
```

The client does not install packages or change system configuration.

Important optional tools:

- `smartctl` — SMART and NVMe health
- `dmidecode` — physical memory-module details
- `lspci` — expanded PCI/GPU driver evidence
- `tpm2_getcap` — TPM capability details
- `mokutil` — Secure Boot state
- `glxinfo` — OpenGL renderer/driver query
- `nvidia-smi` — NVIDIA adapter, driver, memory, and temperature details
- `journalctl` — kernel-event evidence; `dmesg` is used as a fallback

Missing optional tools result in **Not Available** or reduced informational evidence, not a false hardware failure.

## Status behavior

- **Fail** is reserved for confirmed calculation mismatches, memory mismatches, physical read/short-read failures, native SMART/NVMe failure evidence, disk hash failures, critical root-filesystem conditions, or severe kernel evidence.
- **Warning** identifies reviewable issues such as failed systemd units, package updates, low root free space, corrected/reset kernel events, unauthorized USB devices, battery wear, or high temperatures.
- **Incomplete** means PCRT could not complete the requested operation because of access, unsupported behavior, missing output, timeout, or an internal error. It is not proof of hardware failure.
- **Not Available** is used when optional Linux interfaces or tools are not present.
- **Info** is inventory or configuration information that does not affect service readiness.

Reports separate these domains:

- Hardware Functional
- Burn-in Stability
- Linux Integrity
- Linux Maintenance
- Security / Configuration
- Network / Power

## Exit codes

```text
0  Scan completed and no confirmed failure was found
1  Client, argument, claim, or report-generation error
2  Scan completed and a confirmed diagnostic failure was reported
3  Reports were created locally, but the server did not acknowledge upload
```

Warnings and incomplete checks do not by themselves change the process exit code from 0, but they remain visible in the report and overall service conclusion.

## Safety

- Physical block devices are opened read-only.
- Distributed drive sampling uses 64-bit offsets and verifies every requested 1 MiB read.
- Access and unsupported-controller errors are Incomplete rather than drive failures.
- Temporary write tests use a file inside the report output filesystem and remove it afterward.
- The client never runs `fsck` against a mounted filesystem.
- The package-update check uses existing local metadata and does not refresh repositories or install updates.
- The memory tests operate only on memory safely allocated by the Linux process and do not replace an offline full-memory diagnostic.
- The RTC check verifies powered-on progression and does not claim to test the CMOS battery.

## Build from source

Requirements:

- Go 1.22 or later

Build and test both release architectures:

```bash
./build.sh
```

Output:

```text
dist/pcrt-diagnostics-linux-amd64
dist/pcrt-diagnostics-linux-arm64
dist/SHA256SUMS
```

Install the matching built binary:

```bash
sudo ./install.sh
```

Then run:

```bash
sudo pcrt-diagnostics --code ABCDE
```

## Development validation

```bash
go test ./...
go vet ./...
```

The automated tests cover:

- Session-code validation
- Known prime-count result
- 52 generated and 50 unique physical-drive sample positions
- Domain-specific scoring
- HTML and JSON report generation
- Session fetch, one-time claim, claim-token status update, four-file multipart upload, and acknowledgement handling

## License

GNU General Public License version 3. See `LICENSE`.
