Release 3.0.2

This commit is contained in:
Kevin Yue committed 2026-10-12 00:26:32 +08:00
1 parent 580b81e7bb
commit 888f288c0d
54 files changed
+4007 -374

No files matched your search

+130
View File
@@ -0,0 +1,130 @@
# WebKitGTK crash recovery
Status: implemented and independently reviewed; KDE VM verification recorded below.
## Outcome and evidence
When a bundled GTK/WebKit app terminates with the recognized Wayland protocol error, retry once with `WEBKIT_DISABLE_DMABUF_RENDERER=1`. GP Connect uses opaque windows in that mode so recovery does not introduce the KDE redraw failure. Normal launches keep their existing rendering behavior.
The KDE VM comparison used the same newly built binaries: transparent windows lost content with DMABUF disabled; opaque main and settings windows remained drawn during focus changes and reopening. The experiment changed native transparency, backing backgrounds, outer corner rounding and modal clipping together. It validates this combination on Fedora KDE/VMware, not the reporter's NVIDIA startup failure. Recorded versions and reproduction commands are in the workspace's `gp_logs/kde-opaque-test-2026-10-11/README.md`.
References: [GP issue #666](https://github.com/yuezk/GlobalProtect-openconnect/issues/666), [Tauri PR #16226](https://github.com/tauri-apps/tauri/pull/16226), and [rendering investigation](../webkit-rendering.md). The upstream PR proposes a warning, not automatic recovery. A protocol error does not prove DMABUF caused the failure; this is a narrowly selected recovery attempt.
## Scope and retry rules
Apply the policy on Linux, FreeBSD and OpenBSD builds using GTK/WebKit. macOS behavior is unchanged. Use the effective child environment after desktop-session restoration and privilege drop, rather than the parent shell environment, to determine eligibility. Nonempty WAYLAND_DISPLAY is required; XDG_SESSION_TYPE alone is insufficient. DISPLAY may coexist with WAYLAND_DISPLAY, so it does not disqualify recovery.
A retry requires all of these:
- The directly monitored bundled gpgui, gpgui-helper or embedded-mode gpauth process exited unsuccessfully (nonzero status or signal).
- Its stderr contained a GDK diagnostic with `Error 71 (Protocol error) dispatching to Wayland display`. Match the diagnostic line, not arbitrary occurrences in an application log, preflight warning or quoted suggestion.
- DMABUF override is absent in the effective child environment. Any explicit value, including `0`, empty or `1`, prevents automatic replacement.
- No cancellation, explicit termination or service shutdown is in progress, and the recovery budget has not been spent.
Do not retry ordinary authentication rejection, successful exit with malformed output, generic crashes, missing executables, version checks, ordinary download helper failures, external-browser auth, callback-handler commands, or a WebKit subprocess crash while the monitored parent survives. Do not use WebKit version, GPU vendor or desktop name as a trigger. No timeout-based detection of flicker or hangs.
For the desktop, allow at most one automatic rendering recovery during a DesktopLauncher lifetime, including the download helper and GUI-requested restarts. Program resolution and helper execution run inside the supervised attempt; a recognized helper crash requests a fresh service credential before resolving again. The helper and GUI share the same observed child runner, log destination, cancellation ownership and single retry budget. The helper already uses an opaque native window. Once selected, the recovered rendering environment remains in effect for later legitimate GUI restarts in that desktop session; nothing is persisted to disk. A second crash is reported and terminates that launch session.
For authentication, allow at most one rendering recovery in one top-level connection attempt, shared across portal and gateway authentication. Keep this budget and selected auth rendering mode in the owning connection workflow. Create a fresh budget at each serialized top-level run_connection_attempt, including existing startup/resume attempts; never reset within portal/gateway fallback or authentication loops. This feature does not schedule new connection attempts or add an automatic reconnect loop. Concurrent connections do not share mutable global recovery state. If the GUI itself already runs with DMABUF disabled, its auth child inherits that setting and has no additional override retry.
The retry preserves the original executable, identity, certificate/TLS options and environment except the DMABUF setting. Do not automatically set WEBKIT_DISABLE_COMPOSITING_MODE, __NV_DISABLE_EXPLICIT_SYNC, or change LIBGL_ALWAYS_SOFTWARE. Keep any user-supplied values unchanged.
## GUI entrypoints
Cover both public launch commands on Linux/FreeBSD/OpenBSD:
- `gpclient launch-gui` starts DesktopLauncher directly.
- A release-build `gpgui` without `--service-credential-on-stdin` delegates to `gpclient launch-gui` through gpgui's existing app::launch_gui function. This wrapper runs before App::new, runtime environment patching and webview initialization. It inherits the caller environment, forwards --minimized, replaces the bootstrap process with gpclient on Linux/FreeBSD/OpenBSD, so signals, cleanup and final exit status belong to the supervisor. macOS retains its existing launch behavior. Keep this handoff: the same DesktopLauncher supervises and retries the actual GUI child, so no second retry loop belongs in the gpgui wrapper.
DesktopLauncher launches the actual GUI with `--service-credential-on-stdin`; that child must not delegate back to gpclient. Test this guard explicitly to prevent recursion. Existing GUI activation via either public command must return without starting another service, GUI or recovery budget. Desktop-file launch entries that use either command receive the same recovery behavior. The current Linux desktop file uses /usr/bin/gpclient launch-gui %u and the BSD desktop file uses /usr/local/bin/gpclient launch-gui %u. Cover these shipped entrypoints; authentication callback URLs remain routed through the existing callback handler without GUI crash recovery.
Release-path verification must run `gpgui` and `gpgui --minimized`, in addition to `gpclient launch-gui`, with a synthetic recognized crash in the actual child. Confirm one service authorization/session owner, one recovery, fresh credentials, propagated rendering environment, cancellation cleanup and final failure status. Test manual DMABUF override through the public gpgui command too. The earlier VM experiment used debug binaries through gpclient and does not verify this release-only delegation branch.
Debug `gpgui` without stdin credentials intentionally uses the development bootstrap socket and runs directly, with no DesktopLauncher supervisor. Opaque appearance still applies when the override is supplied, but automatic desktop crash retry is a release-launch feature; do not add a separate self-restart loop for the development path. Direct internal launches with `--service-credential-on-stdin` require their existing supervising caller. macOS app-bundle launch remains unchanged.
## Process observation module
Put the classifier and bounded stderr observer under gpapi::process, alongside the current launchers. Keep policy independent of gpservice transport models. GUI and auth launchers use the same classifier; their owners control retry sequencing and budgets.
Capture and continuously drain stderr while the child runs. Forward the original bytes to the existing destination: inherited stderr for auth, append-only GP_LOG_FILE for GUI when supplied, otherwise inherited stderr. Do not route stderr through stdout: gpauth stdout is the bounded credential JSON channel. Do not duplicate child messages through the Rust logger. Emit the parent's retry/final-failure records through the existing logger and selected log format.
The observer retains only a fixed-size rolling diagnostic fragment and a match flag, not full stderr. It handles read chunks splitting a diagnostic and lines exceeding the bound without unbounded allocations. Matching does not require storing a username, SAML request or cookie. A stderr observer read/forwarding error is a launch error, not a crash classification. A GUI credential-write BrokenPipe can be a consequence of the early abort: retain that error while observing and reaping the child. If the unsuccessful exit and GDK diagnostic confirm the rendering failure, return that classification; otherwise return the original write error. Never treat BrokenPipe alone as a recovery trigger. Drain both stdout and stderr concurrently for auth to avoid pipe deadlocks; keep the current auth stdout size limit. Do not change generic controlled command execution into a WebKit-specific runner: add only the output observation seam needed by the auth launcher, retaining its process-group cancellation and reaping guarantees.
Represent completion as exit status plus a classified rendering failure, rather than parsing anyhow display text. Launch errors remain errors. Check exit status before decoding credential JSON so an aborted authenticator reports its failure rather than only "Failed to parse auth data". Discard partial credential output on every failed attempt.
Cancellation must close/kill and reap the owned process group, finish or cancel and join the pipe readers, and never start the retry. GUI launch futures currently use kill_on_drop; any new reader tasks need explicit ownership and cleanup when DesktopLauncher's select cancels them. Pipe draining after direct-child exit is bounded: inherited pipes held open by helpers must not block completion indefinitely; stop owned helpers and finish readers. User cancellation wins a race with classification at the retry decision.
## Desktop GUI recovery
GuiLauncher owns one GUI attempt: version resolution, process spawning, credential writing and observation. It returns the attempt outcome; DesktopLauncher owns the retry decision, rendering mode and lifetime budget. Resolve the executable once for the initial attempt and use that same selected executable on recovery; do not download another GUI after a rendering crash.
Do not resend an old service credential. Extend the private desktop control pipe with a named rendering-retry message, distinct from the existing GUI-exited message. After the failed child and its readers have stopped, DesktopLauncher sends that message. DesktopClient revokes the old session and issues a fresh credential, without requiring gui_restart_requested. Rendering renewal consumes and clears any pending gui_restart_requested intent from the old session, rather than leaving it to authorize a later unintended restart. It limits this explicit rendering renewal to once per desktop channel. Invalid/repeated recovery messages fail closed. Keep the existing ordinary restart message behavior and EOF shutdown behavior.
The parent then launches the same GUI with the fresh credential and child-only DMABUF override. Continue monitoring service exit and credential-channel errors throughout renewal and retry. Preserve initial minimized intent for startup recovery; legitimate later GUI restarts retain current non-minimized semantics. If renewal or retry fails, close the control input and let the service shut down normally. Report the original rendering failure plus the recovery failure, including exit statuses, without credential bytes.
Rendering recovery is not VPN recovery. No portal login, tunnel reconnection or restoration of an interrupted authentication is initiated by restarting the GUI. Revoking the old session follows existing service ownership/disconnect rules; do not promise uninterrupted VPN traffic after a GUI crash.
## Authentication recovery
SamlAuthLauncher owns one attempt and reports a typed recognized rendering failure after draining output and reaping the process group. Automatic auth retry is allowed only for the bundled embedded authenticator; a configured custom executable must not be restarted or overridden. External-browser and callback paths are unchanged.
The CLI connection workflow and gpgui PortalConnector own the auth recovery. On the typed failure, spend the connection's retry budget, select DMABUF-disabled auth mode, discard partial output, and obtain a fresh prelogin for the same portal/gateway with the existing profile, client certificate options and cancellation token. Re-evaluate the server's authentication mode from the fresh response. If it now chooses standard or external-browser auth, follow that path without imposing an embedded WebKit retry. Return the replacement Prelogin together with its Credential from the owning prelogin/auth operation, so callers use refreshed region and authentication metadata instead of keeping the original Prelogin. Preserve existing gateway standard-auth password fallback when fresh prelogin changes to Standard. Do not replay an already navigated SAML request, and do not repeat portal config retrieval or gateway login after they have succeeded.
Pass the selected child rendering mode through SamlAuthLauncher, applying it after into_non_root desktop restoration. Subsequent embedded auth windows in that connection use the selected mode but cannot spend another recovery budget. Preserve the one-shot --clean behavior: do not clear browser state again if the first attempt already consumed it. If the fresh prelogin fails or auth fails again, return that error with rendering-recovery context. Explicit cancellation remains AuthenticationCancelled rather than a crash error. Wrap every failure after spending the recovery budget in a typed terminal recovery error (except cancellation, which keeps its existing type). Every fallback owner must preserve and stop on this type: portal-to-gateway fallback, cached-credential fallback, automatic gateway candidate iteration, internal gateway iteration, and the GUI stops_gateway_attempts decision. Do not inspect anyhow message text. Exhausted recovery must never cause another authentication window through those paths.
The existing gpauth native auth window is opaque; confirm all embedded windows and backing surfaces remain opaque under this setting. GP Connect's GUI also launches gpauth through SamlAuthLauncher, so both caller paths are covered.
## Opaque window appearance
In gpgui, derive immutable process rendering mode at startup on Linux/BSD: WEBKIT_DISABLE_DMABUF_RENDERER exactly `1` means opaque windows. This applies equally to manual overrides and automatic recovery. No extra production environment variable or persisted setting is needed; remove the VM-only GP_TEST_OPAQUE mechanism when implementing production behavior.
Extend the existing WindowAppearance value with `opaqueWindow`. One resolved value supplies main, settings and update native builders, initial URL data, generated bindings and runtime appearance notifications. Set native transparency false before creating any webview, disable outer corner rounding regardless of the saved preference, and remove outer modal clipping. Do not mutate the saved rounded-corner preference. Disable the corner preference control while opaque mode is active so it does not promise an unavailable effect.
Use the existing theme background token for HTML, body and root, including first paint, light/dark mode and runtime theme switches. The inline head bootstrap in each of the three HTML entrypoints reads opaqueWindow and applies the initial appearance before AppShell CSS or React loads; renderToRoot initialization alone is too late to guarantee the first paint. Native backing color must agree with the initial theme where supported, without a transparent flash. The existing Rust theme application path owns native background updates for all existing windows, including system-theme change events, while frontend theme handling updates the shared CSS tokens. New windows resolve the current theme before construction; AppHandle.set_theme alone is not sufficient for explicit native backing colors. Internal buttons/cards retain their normal rounding. Keep custom title bars and their dimensions. An update window created later receives the same immutable rendering mode. macOS panel configuration is unchanged.
## Logging and diagnostics
Log one warning before recovery: the app exited with a Wayland rendering error and is being restarted with DMABUF disabled (opaque windows for GUI). Preserve the failed-attempt stderr in the normal log destination. On second failure, report both attempts' exit statuses and a useful instruction to attach diagnostics; never dump auth stdout, command arguments or environment maps. Add the effective DMABUF setting to diagnostics only if not already collected. Do not send new telemetry or persist an automatic override.
## Verification before implementation is accepted
- Process fixtures emit the real diagnostic across chunk boundaries and with large stdout/stderr. Verify no deadlock, one retry, unchanged stdout JSON, original stderr delivery, bounds and actual final errors.
- Negative fixtures: preflight warning quoting the diagnostic, normal exit, nonzero auth rejection, unrelated abort, explicit override values, custom auth executable, external browser, X11, cancellation and exhausted retry budget.
- Desktop pipe integration: fresh credential/session ID on rendering renewal; old credential revoked; repeated renewal rejected; ordinary restart still works; a pending ordinary restart followed by rendering renewal does not authorize another unrequested exit/restart; service EOF/error during renewal does not hang or leave a child. Test cancellation at spawn, credential write, reader wait and retry transition.
- Auth workflow fixtures for CLI and GUI: two distinct prelogin requests, no SAML request replay, recovery shared across portal/gateway, no new clean-state reset, no outer fallback after terminal rendering failure, valid second credential used once, and cancellation during fresh prelogin.
- Opaque appearance tests and frontend build: theme-aware backgrounds, all window types, saved corner preference retained but forced off, no macOS effect.
- Run targeted gp Rust checks/tests and gpgui Rust check/frontend build using the actual sibling gp checkout.
- Repeat the KDE transparent/opaque comparison with production code: main/settings/update, hover, input focus, hide/show and theme changes. Use a synthetic child crash to exercise supervision on the VM; report separately from real rendering tests.
- Confirm the real crash workaround on the affected NVIDIA system when available. Linux KDE testing does not prove FreeBSD/OpenBSD behavior; perform supported cross-target checks and explicitly report remaining runtime gaps.
## Implementation order
1. Shared classification/observation and attempt outcomes with process fixtures.
2. Desktop credential renewal and bounded GUI recovery.
3. Theme-aware opaque appearance in gpgui and verification on KDE.
4. Fresh-prelogin auth recovery in both owning workflows.
5. End-to-end cancellation/negative tests, diagnostics/docs and independent implementation review.
No release or deployment is included in this change.
## Design review outcome
Three independent agents reviewed process/service lifecycle, authentication workflows, and GUI appearance against the current code. Their findings were incorporated and the revised sections reviewed again. All three reported no remaining blocking design findings.
Changes from review: retain early credential BrokenPipe long enough to classify a confirmed crash; clear old-session restart intent during credential renewal; propagate replacement prelogin metadata and preserve standard gateway password reuse; stop every fallback path on terminal recovery failure; define budgets per serialized connection attempt; initialize opacity before CSS loads; and keep native backing colors synchronized through existing theme ownership.
Design review preceded implementation. Three independent implementation reviews covered process/service lifecycle, authentication workflows and GUI appearance. Findings were fixed and re-reviewed with no remaining blockers.
Entrypoint follow-up: code inspection confirmed the release gpgui command delegates before creating a webview. The design now explicitly covers that route, its stdin recursion guard, minimized/environment forwarding and release-build verification; debug direct-launch supervision remains outside the production retry scope.
## Implementation verification
Both repos compile against the actual sibling checkout. Targeted checks passed: 41 gpapi process tests; six desktop-service tests (one subprocess helper ignored); six CLI auth-flow tests; four GUI auth recovery tests; 16 GUI utility tests; nine frontend appearance/settings tests and the frontend build.
On Fedora 44 KDE Wayland (Plasma/KWin 6.6.4, WebKitGTK 2.54.1, VMware vmwgfx), a VM-only fixture emitted the reported GDK protocol-error diagnostic and aborted the first supervised child. Both public launch paths recovered once, delivered a fresh credential/session ID and launched the real opaque GUI. Main/settings remained fully rendered during focus changes. Minimized intent survived retry, and activating the existing GUI did not start another child. Explicit DMABUF=0 prevented retry. Two recognized crashes stopped with both failures visible. Ctrl+C cleanup passed through both public paths after Linux/BSD gpgui bootstrap was changed to process replacement.
This validates supervision using a simulated crash, not the actual NVIDIA failure. The VM build used release entrypoints with optimization disabled. Update-window runtime appearance, live system-theme changes, affected NVIDIA hardware and FreeBSD/OpenBSD runtime remain unverified; window construction and appearance behavior are covered by inspection and targeted tests. Detailed evidence is in workspace gp_logs/kde-crash-recovery-2026-10-11/.
Manual KDE confirmation: after the simulated first-launch crash, the user tested the recovered real GUI and reported no flickering. This confirms the tested VM behavior; affected NVIDIA hardware and BSD runtime remain separate verification gaps.
Helper follow-up: two independent implementation reviews found no blockers. The helper shares the GUI's monitored child runner and desktop recovery budget. Local process tests passed (45), Linux VM process tests passed (48), and the sibling gpgui check passed. A simulated helper GDK error/SIGABRT renewed the credential and launched the real opaque helper with DMABUF disabled. Clicking and changing keyboard focus preserved its content. Cancellation reaped the test children; repeated crashes stopped after two attempts; ordinary failures and an explicit DMABUF override did not retry. The VM used a mock service credential channel and blocked downloads to avoid changing the installed application, so successful installation and the complete helper-to-GUI transition were not tested. Evidence is in workspace gp_logs/helper-crash-recovery-2026-10-12/.
+103
View File
@@ -0,0 +1,103 @@
# 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.
+89
View File
@@ -0,0 +1,89 @@
# Collect diagnostics for a bug report
The diagnostic collector gathers app and system versions, desktop and graphics
information, and a small set of rendering environment variables. It does not
connect to a VPN, launch the GUI, read credentials or logs, upload a report, or
change settings.
Run it from a terminal in your normal desktop session, **without sudo**, so it
can see the desktop environment used by the application. Linux, macOS, FreeBSD,
and OpenBSD are supported. Missing tools or unavailable information are reported
without preventing collection.
## Installed versions with the diagnostics command
```sh
gpclient diagnostics
```
To save a report to a new file:
```sh
gpclient diagnostics --output diagnostics.txt
```
For structured output:
```sh
gpclient diagnostics --json --output diagnostics.json
```
The collector refuses to overwrite an existing file. Choose another filename or
remove the previous report yourself before collecting again.
This command is being added after 3.0.1. If your installed version says the
command is unknown, use the standalone script below. You do not need to upgrade
before reporting a problem.
## Older versions: standalone script
The standalone script collects the same information in a readable format. It
requires a POSIX shell and common system utilities, without Python or jq.
Download the script to a local file:
```sh
curl --fail --location \
https://raw.githubusercontent.com/yuezk/GlobalProtect-openconnect/dev/scripts/collect-diagnostics.sh \
--output collect-diagnostics.sh
```
Open `collect-diagnostics.sh` in a text editor and review it before running it.
Then, as your normal desktop user:
```sh
sh collect-diagnostics.sh
```
Or save the report to a new file:
```sh
sh collect-diagnostics.sh --output diagnostics.txt
```
The download points to the development branch because this collector was added
after 3.0.1. It becomes available there when the change is published. From a
local checkout containing the change, run
`sh scripts/collect-diagnostics.sh` instead. Do not pipe a downloaded script
directly into a shell.
## Review before sharing
Read the report before pasting it into an issue or attaching the saved file.
It includes executable paths with your home directory shortened to `~`, raw
desktop/session identifiers, and selected rendering overrides. These values can
contain identifying information, so the report is **not guaranteed anonymous**.
Remove any private information before posting. Never share passwords, cookies,
tokens, SAML payloads, private VPN addresses, or a complete environment dump.
Diagnostics do not include logs. For CLI issues, share the relevant terminal
output separately after reviewing it. For GUI issues, use the app's built-in
option to open or export logs, if available. Avoid posting full verbose logs
unless requested, as authentication output can contain sensitive data.
Include your installation method and the exact command or GUI steps that fail.
Replace private portal names with `<portal>` and omit credentials. If you cannot
run the collector, provide the app version, OS, and relevant desktop,
GPU/driver, or WebKitGTK details manually. Graphics details are useful for
window failures but are not needed for every connection problem.
+87
View File
@@ -0,0 +1,87 @@
# WebKitGTK rendering investigation
## KDE redraw failure with either WebKit override
On October 11, 2026, local KDE tests reproduced GUI flickering and incomplete
redraws with either override alone and with both overrides enabled. All three
commands exhibited the problem:
```sh
WEBKIT_DISABLE_DMABUF_RENDERER=1 gpclient launch-gui -vv
WEBKIT_DISABLE_COMPOSITING_MODE=1 gpclient launch-gui -vv
WEBKIT_DISABLE_COMPOSITING_MODE=1 \
WEBKIT_DISABLE_DMABUF_RENDERER=1 \
gpclient launch-gui -vv
```
The window intermittently loses most of its content. Hovering a button or
focusing an input redraws that control while other regions remain missing.
The supplied screenshots show the desktop behind missing regions of the GUI,
with only some controls still visible. Earlier testing reported normal
rendering after removing the overrides.
Each override independently triggers the observed problem on the tested KDE
setup. The tests do not establish the underlying rendering defect or whether
other graphics configurations are affected. The exact application version,
KDE version, display protocol,
GPU/driver, and WebKitGTK version were not recorded with this test.
Do not recommend either override as a general GUI workaround. Close the app
completely between rendering tests so each launch uses the intended environment.
These command-scoped settings do not persist after the application exits.
## KDE test with NVIDIA explicit sync disabled
On the same KDE setup, the following command did not cause the flickering or
incomplete redraws observed with either WebKit override:
```sh
__NV_DISABLE_EXPLICIT_SYNC=1 gpclient launch-gui -vv
```
This establishes that the setting did not reproduce the redraw problem in this
local test. It does not establish whether it fixes the authentication-window
failure in #666 or whether the tested graphics driver uses this setting.
## Relationship to the authentication-window investigation
[Issue #666](https://github.com/yuezk/GlobalProtect-openconnect/issues/666)
reports a separate authentication-window failure on Hyprland with
`Error 71 (Protocol error) dispatching to Wayland display`. Whether that failure
shares a cause with this KDE redraw problem is not confirmed.
The automatic `WEBKIT_DISABLE_COMPOSITING_MODE=1` and
`WEBKIT_DISABLE_DMABUF_RENDERER=1` settings were removed in 3.0.0. Automatically
setting `LIBGL_ALWAYS_SOFTWARE=1` when missing on Wayland remains in place.
Restoring either WebKit override globally would risk reintroducing the observed
redraw failure.
[WebKit bug #280210, comment 14](https://bugs.webkit.org/show_bug.cgi?id=280210#c14)
also describes incomplete rendering with DMABUF disabled on an NVIDIA/KWin
setup. It reports `__NV_DISABLE_EXPLICIT_SYNC=1` as an alternative that retains
DMABUF rendering. Other comments report flickering with that alternative, so it
requires testing on the affected machine; it is not a validated general fix
for GP Connect. The local KDE test above found no redraw failure with this
alternative, but the reporter's crash still needs a separate test.
## Opaque GUI recovery verification
The local implementation selects `WEBKIT_DISABLE_DMABUF_RENDERER=1` only for a
single retry after a recognized Wayland GDK rendering crash. An explicit caller
setting prevents automatic selection. With that value exactly `1`, the GUI uses
opaque, square main/settings/update windows while retaining the saved corner
preference. It does not select `WEBKIT_DISABLE_COMPOSITING_MODE`.
On the Fedora 44 KDE Wayland VM (Plasma/KWin 6.6.4, WebKitGTK 2.54.1,
VMware vmwgfx), a simulated GDK crash followed by the real opaque GUI rendered
the main and settings windows fully during focus changes through both public
launch commands. This supports the opaque approach on this VM; it does not
prove the original NVIDIA crash is resolved or establish behavior on every
KDE setup. See [the recovery design](design/webkit-crash-recovery.md) for the
retry boundaries and remaining verification gaps. The earlier warning about
general overrides concerns the transparent-window behavior tested above.
The user also manually tested the recovered GUI on this VM and confirmed no
flickering.