Skip to content

feat(doctor): check the named distro, staged agent, hvsocket registration and the port - #105

Merged
zcsizmadia merged 2 commits into
mainfrom
feat/doctor-checks
Sep 5, 2026
Merged

zcsizmadia merged 2 commits into
mainfrom
feat/doctor-checks

Conversation

@zcsizmadia

Copy link
Copy Markdown
Collaborator

Closes #77.

wsldrive doctor checked WinFsp, wsl.exe and the default distro. That left it unable to answer the questions people actually arrive with — including the one the Direction B setup notes explicitly send them to doctor for.

doctor [--distro X] [--hvsocket] [--port N] [--pause]
check why
--distro X runs a command in that distro mount --distro X otherwise fails later, for its own reasons, on a name that was simply wrong
staged ~/.local/bin/wsldrived a mount that auto-launches the agent fails at launch, not at configure. A warning, not a failure: --agent can point elsewhere
--hvsocket counts the GuestCommunicationServices GUIDs the check Direction B users are sent here for, which doctor could not answer
--port N binds the loopback port a stale agent holding it is named now, instead of surfacing later as a confusing mount failure
--pause holds the console open the Inno postinstall ran doctor in a window that closed before the report could be read; it now passes --pause

Unknown options are refused with exit 2 rather than ignored.

It found a real problem on the first run. The ten hvsocket registrations this machine was set up with are gone — 0/10 — which I confirmed independently against the registry before trusting the check, so it is a true negative and not a wrong key path.

Verification

doctor                                   -> all ok, exit 0
doctor --distro Ubuntu --hvsocket --port 5700
  [ok]   distro 'Ubuntu' runs commands
  [ok]   agent staged in Ubuntu (~/.local/bin/wsldrived)
  [fail] only 0/10 hvsocket GUIDs registered for ports 5700-5709
  [ok]   TCP port 5700 is free      -> exit 1
doctor --distro NoSuchDistro             -> distro check fails, agent check warns
doctor --bogus                           -> exit 2

The wizard still compiles. Windows-only code, so Linux is untouched: 126/126 and conformance 31/0 there; Windows 124/124.

…on and the port

`wsldrive doctor` checked WinFsp, wsl.exe and the *default* distro. That left it
unable to answer the questions people actually arrive with, including the one
the Direction B docs send them to doctor for.

  doctor [--distro X] [--hvsocket] [--port N] [--pause]

- --distro X runs a command in that distro. `mount --distro X` would otherwise
  fail later, for its own reasons, on a name that was simply wrong.
- The agent staged at ~/.local/bin/wsldrived is checked in the named distro (or
  the default). Reported as a warning, not a failure: --agent can point
  elsewhere.
- --hvsocket counts the GuestCommunicationServices GUIDs for the port range and
  says how to fix a shortfall. This is the check the Direction B setup notes
  point at, and doctor had no answer for it. It found a real one here: the ten
  registrations this machine was set up with are gone, 0/10.
- --port N binds the loopback port to see whether it is free, so a stale agent
  holding it is named now rather than surfacing as a confusing mount failure.
- --pause holds the console open. The Inno postinstall task runs doctor in a
  window that closed before the report could be read; it now passes --pause.

Unknown options are refused with exit 2 rather than ignored.

Verified on this machine: a clean run passes and exits 0; --distro Ubuntu
--hvsocket --port 5700 reports the distro and staged agent ok, the port free,
and the missing GUIDs as a failure with exit 1 - independently confirmed
against the registry, so it is a true negative and not a bad key path; a
nonexistent distro fails the distro check and warns on the agent; --bogus exits
2. The wizard still compiles. Windows-only code, so Linux is untouched:
126/126 there and conformance 31/0, Windows 124/124.

Closes #77
@zcsizmadia zcsizmadia added the enhancement New feature or request label Sep 5, 2026
The doctor helpers are guarded by _WIN32, but their dependency was included
under the narrower WSLDRIVE_HAVE_WINFSP. That builds on a machine with the
WinFsp SDK installed - mine - and fails on the plain Windows CI job, which does
not install it:

  error C2039: 'to_wide': is not a member of 'wsld'

Caught by CI, which is the only place that configuration is built.
@zcsizmadia
zcsizmadia merged commit 9dd54fb into main Sep 5, 2026
6 checks passed
@zcsizmadia
zcsizmadia deleted the feat/doctor-checks branch September 5, 2026 15:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

doctor: check the named distro, hvsocket registration, the staged agent and the loopback port

1 participant