mirror of
https://github.com/yuezk/GlobalProtect-openconnect.git
synced 2026-11-19 06:26:14 -05:00
104 lines
5.9 KiB
Markdown
104 lines
5.9 KiB
Markdown
# Diagnostics collection design
|
|
|
|
## Purpose
|
|
|
|
`gpclient diagnostics` collects support information without starting a VPN,
|
|
opening a window, accessing credentials, reading logs, or making network
|
|
requests. A standalone script provides the same collection for older releases.
|
|
Users review the report before attaching it to a public issue.
|
|
|
|
## Interface
|
|
|
|
- `gpclient diagnostics`: readable report on stdout, no sudo needed.
|
|
- `gpclient diagnostics --json`: the same fields as a JSON object, with a schema
|
|
version. It contains information, not log events.
|
|
- `gpclient diagnostics --output PATH`: save the selected format to a new file;
|
|
refuse to overwrite an existing file.
|
|
- `sh collect-diagnostics.sh`: the same readable report for older installations.
|
|
- `sh collect-diagnostics.sh --output PATH`: save to a new file. The standalone
|
|
script needs only POSIX shell and common base utilities, not Python or jq.
|
|
|
|
The script is shipped in `scripts/collect-diagnostics.sh`. The CLI embeds that
|
|
exact file at compile time and runs it with `/bin/sh`; no installed script is
|
|
needed. It supplies its own build version instead of recursively invoking
|
|
`gpclient`. JSON formatting and file output are responsibilities of the Rust
|
|
command. The script emits stable `field: status: value` lines; values are
|
|
flattened to one line. JSON has `schema_version: 1` and `fields`, a map of field
|
|
names to `{status, value}` objects. Status is `ok`, `unset`, `unavailable`,
|
|
`failed`, `timed_out`, or `not_applicable`; absent values become null. Unknown
|
|
fields, statuses or duplicate keys are rejected by the Rust parser. Fields
|
|
cover system, app paths/versions, GUI metadata, execution context, desktop,
|
|
graphics/packages, and the environment allowlist below.
|
|
|
|
## Collection and platform coverage
|
|
|
|
Common fields: report schema, OS/kernel release and architecture, gpclient and
|
|
gpauth versions, executable locations, normal-user versus root execution,
|
|
presence of an SSH session, VM indicators when available, and installation
|
|
location hints. A location hint does not claim a package-manager provenance
|
|
that cannot be verified. Executable paths replace the home directory with `~`.
|
|
Only known version options are invoked; the GUI application is not launched to
|
|
discover its version.
|
|
|
|
Linux, FreeBSD and OpenBSD: raw desktop/session identifiers, display protocol
|
|
inferred from presence of display variables (their socket values are excluded),
|
|
graphics device/driver summaries, available package versions for WebKitGTK,
|
|
GTK and graphics drivers. Linux reads selected `/etc/os-release` fields and
|
|
uses available package-manager queries. BSD uses its own base utilities and
|
|
package names, rather than assuming Linux `/proc`, `lspci`, or `pacman` exist.
|
|
macOS uses `sw_vers`, bundle paths and a filtered graphics model probe; Linux
|
|
graphics and desktop fields are marked not applicable.
|
|
|
|
Environment allowlist: `XDG_CURRENT_DESKTOP`, `XDG_SESSION_DESKTOP`,
|
|
`XDG_SESSION_TYPE`, `DESKTOP_SESSION`, `WEBKIT_DISABLE_DMABUF_RENDERER`,
|
|
`WEBKIT_DISABLE_COMPOSITING_MODE`, `LIBGL_ALWAYS_SOFTWARE`,
|
|
`__NV_DISABLE_EXPLICIT_SYNC`, `GDK_BACKEND`, `GDK_GL`. Values are capped and
|
|
flattened; HOME, DISPLAY, WAYLAND_DISPLAY, DBUS addresses, hostname, username,
|
|
machine IDs, network configuration and arbitrary environment variables are
|
|
excluded. Desktop identifiers are raw user-controlled strings, so reports are
|
|
not guaranteed anonymous and must be reviewed before sharing.
|
|
|
|
Parse OS-release assignments as data without sourcing them. Strip control bytes
|
|
and line breaks, cap each value at 512 bytes, and decode invalid UTF-8 lossily
|
|
in Rust. Reports are capped at 64 KiB. Diagnostics dispatches before generic
|
|
OpenSSL setup even if global CLI compatibility flags are supplied.
|
|
|
|
Optional probes report `unavailable`, `timed_out`, or `failed` without stopping
|
|
collection. Each external probe has a three-second timeout and a 64-KiB output
|
|
cap. A watchdog terminates the probe and its discoverable descendants using
|
|
PID/parent-PID snapshots, and the collector reaps the direct child and cancels
|
|
the watchdog. Signal cleanup also stops active probes and watchdogs. This is
|
|
best-effort tree cleanup for trusted local system utilities: a process that
|
|
deliberately reparents/daemonizes can escape it. No such probes are selected.
|
|
Tests cover descendants, ignored TERM, output flooding and interruption. Probe
|
|
stderr is discarded rather than pasted into the report. No packages are
|
|
installed. No privilege escalation or rendering workaround is applied.
|
|
|
|
## Issue form
|
|
|
|
Replace the Markdown template with a GitHub YAML issue form. Require affected
|
|
component, app version, installation method, OS, and reproduction steps including
|
|
expected and actual behavior. Ask for last working version/system changes,
|
|
diagnostics, relevant logs and screenshots as optional fields. Provide the new
|
|
command and a download/review/run path for the standalone script. Reporters may
|
|
instead enter desktop, GPU/driver and WebKit information manually. Authentication
|
|
reports should name embedded/external browser and the failure stage; credential
|
|
storage details are requested only when relevant. Warn against sharing passwords,
|
|
cookies, tokens, SAML payloads or complete environment dumps. Do not require
|
|
running workaround flags or upgrading before reporting a regression.
|
|
|
|
## Verification
|
|
|
|
Test the shared collector with controlled command/environment fixtures: missing
|
|
tools, hung probes, sensitive data excluded, home path sanitization, version
|
|
recursion avoided, and OS-specific selection for Linux/FreeBSD/OpenBSD/macOS.
|
|
Test CLI parsing, schema/JSON conversion and overwrite refusal. Run shell syntax
|
|
checks, targeted Rust checks/tests, and a real local macOS report. BSD/Linux fixture
|
|
coverage validates selection/parsing; it is not native runtime verification.
|
|
|
|
## Scope
|
|
|
|
No log bundling, uploading, connectivity tests, package installation, configuration
|
|
changes, GUI integration or crash recovery. The diagnostics module owns collection
|
|
and formatting; existing session/service transport models are not involved.
|