Vantage/vantage-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Self review of doc pages

Browse Source
This commit is contained in:
mrhid6
2026-08-10 16:32:23 +01:00
parent bd7b3256fc
commit 83c38db92e
34 changed files with 860 additions and 991 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/vantage/ssh-keys.md
+15 -18
View File
@@ -22,14 +22,12 @@ fingerprint, and never needs the private half for this path.
### Generate one on a server
Vantage can have an agent generate a keypair on a managed machine
(`GenerateKeyCmd` over the command stream). The public half comes back to the
library. You may optionally upload the private half too, in which case it is
Vantage can have a managed machine generate a keypair for you. The public half
comes back to the library. You may optionally upload the private half too, in which case it is
stored **AES-256-GCM encrypted** under `KEY_ENCRYPTION_KEY`.
The JSON representation of a key exposes only `has_private_key` and
`has_passphrase` never the material. Retrieving a stored private key is its
own endpoint and its own audit event.
Vantage never displays stored private key material in a list. Retrieving one is
a separate, deliberate action, and it is written to the audit log.
:::tip Why store a private key at all
The [browser console](./browser-console.md) needs one to open an SSH session. If
@@ -38,13 +36,13 @@ you are not using the console, do not upload private halves.
## Assigning
Assign a key to one or more servers. Within one poll interval 30 seconds the
agent picks up the change.
Assign a key to one or more servers. The agent picks up the change within about
30 seconds.
## Revoking
Revocation is **soft**: the assignment gets a `revoked_at` timestamp rather than
being deleted, so the history of who had access to what, and when, survives.
Revoking marks the assignment revoked, with a timestamp, rather than erasing it,
so the record of who had access to what, and when, survives.
The agent treats a revoked assignment as "not desired" and removes the line from
`authorized_keys` on its next sync.
@@ -60,13 +58,12 @@ Each poll:
1. The control plane returns the desired set of public keys for that server.
2. The agent reads `/root/.ssh/authorized_keys` and computes fingerprints.
3. **If the sets match, it writes nothing.** No disk churn on unchanged state,
which is most polls.
4. If they differ, it writes a temporary file, then `os.Rename()`s it over the
real one and sets mode `0600`.
3. **If they match, it writes nothing.** That is true of almost every check.
4. If they differ, it writes the new file alongside the old one and swaps it in
one step.
The rename is atomic, so a machine that dies mid-write keeps the old file
intact. There is no window in which `authorized_keys` is truncated or partial.
The swap cannot be interrupted halfway, so a machine that loses power mid-change
keeps its old, working file.
:::danger Vantage owns the whole file
The agent rewrites `authorized_keys` to match the desired set. Keys added by
@@ -77,5 +74,5 @@ it in Vantage.
## Recovering from a lockout
If you have removed every key from a machine and cannot get in, you still have
the console provided a private key is stored or out-of-band access from your
hosting provider. Vantage has no backdoor and does not keep a break-glass key.
the console, provided a private key is stored, or whatever out-of-band access
your hosting provider offers. Vantage has no backdoor and does not keep a break-glass key.