canonical / canonical/multipass
Feature request: a `multipass doctor` command for diagnosing daemon/backend/network issues
Nobody has claimed this yet.
- Dominant language
- C++
- Stars
- 9.2k
- Forks
- 829
- Avg merge
- 3d 2h
- Merged PRs (30d)
- 45
Description
Recently my multipassd ended up in a bad state and none of my commands worked
until I went digging through the daemon logs and the troubleshooting docs to
work out what was wrong. It made me wish there was a single command that just
tells you what's broken, the way `brew doctor` or `flutter doctor` do.
Right now when something breaks (socket unreachable, backend not responding, a
VM stuck in a weird state, no networking inside the guest) you usually find out
through a cryptic error and then go hunting. A lot of those checks already exist
as manual steps in the troubleshooting guide, so this would mostly be automating
what's already documented.
Rough idea:
multipass doctor # prints a health report
multipass doctor --json # same, machine readable, useful for bug reports
Things it could check:
- daemon: multipassd running, gRPC socket present, CLI can reach the daemon,
client/daemon versions compatible
- backend: which one is active, binaries present, backend responding
- instances: process actually alive, stale lock files, "Running" but not really
- networking: NAT/vmnet/DHCP on the host, a VPN that might be hijacking routes,
subnet clashes; on the guest, default route + gateway + DNS + internet
- mounts and storage: dead SSHFS mounts, missing host dirs, locked qcow2, disk full
Roughly what the output might look like:
✓ daemon running
✓ gRPC socket present
✗ internet unreachable from guest
⚠ VPN detected (Cloudflare WARP), may be interfering with NAT
I saw #775 about internal backend health checks. This is related but aimed at
the user-facing CLI rather than backend selection, so I didn't want to assume
it's the same thing.
Before writing any code I wanted to check a couple of things with you:
- would you want the checks running in the daemon and exposed over gRPC, or
done client-side?
- any appetite for an optional `--fix` later that does safe recovery (restart
daemon, clear stale locks, fix socket perms)? I'd keep anything destructive
out of the default and behind explicit flags, but only worth designing if
that direction is wanted at all.
I'd like to work on this if it's something you'd take.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the troubleshooting guide and its existing manual checks, then inspect the user-facing CLI entry points for how a new command would be registered. Review issue #775 for the internal backend health-check context. Done requires an agreed scope and architecture for daemon or client checks, human-readable output, and the optional JSON report.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cpp, grpc
- Domain
- backend, cli, networking
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100