| name | relay-revoke-device |
| description | Revoke a single client device's access to the relay without affecting the others: remove its --allow-cn from ghostunnel, restart ghostunnel, and re-baseline the health check. Use when the user wants to deauthorize / remove / kick a device, a laptop is lost or compromised, or a rogue --allow-cn was found by the health check. |
| allowed-tools | Read, Edit, Bash, Agent, AskUserQuestion, TodoWrite |
Revoke a client device
Read CLAUDE.md. Because each device has its own CN, removing one --allow-cn revokes exactly that
device — everyone else stays up (the server cert is untouched).
First, confirm WHICH CN
Ask the user which device/CN to revoke. If this is a response to a health-check ATTENTION REQUIRED
finding (a --allow-cn you didn't add), treat it as intrusion: revoke it, then inspect how it got
there and consider rotating the CA + all client certs.
Steps (delegate VPS work to the relay-operator agent)
- Back up the unit (
*.bak.<ts>).
- Remove
--allow-cn zt-relay-client-<N> from the ghostunnel server unit. (Revocation is by CN, so
dropping the --allow-cn is sufficient — no client-ca.crt change.)
sudo systemctl daemon-reload && sudo systemctl restart ghostunnel-server; confirm active.- Re-baseline:
bash local/healthcheck-pull.sh --update-baseline so the removed CN doesn't show as
drift.
Verify
- The revoked device now fails at the mTLS handshake (unknown/!allowed CN).
- A still-authorized device still works.
- Next health pull is clean.
Escalation (lost / compromised device)
If the device or its key may be in someone else's hands, also consider rotating the CDN service token
(re-run the provisioning script) and — if the relay CA itself could be exposed — the full CA +
client-cert rotation, which re-issues every device.
Guardrails
- Never remove the wrong CN — confirm with the user. Never touch the server cert/key in the revoke path.
- Never weaken an invariant. Re-baseline only this intentional change, nothing else.
