# Connect SSH host to Prodpeek

Profile: `ssh/diagnostics-read` · connection kind: `ssh` · tier 2
Credential: Private key PEM (or a password)
Suggested URL: `diag@host.example.com:22`

A fixed menu of diagnostic commands on a Linux host. Not a shell — the adapter has no free-form command tool and never will.

## What you must not do

You cannot create this credential on the user's behalf — it needs their login and,
usually, an approval step. Walk them through it and verify the result. Never ask
them to paste the credential into the chat; it goes straight into Prodpeek's
console, which encrypts it at rest. You can generate the keypair and print the public key for the user to install, but do not install it yourself unless they have given you an admin session — and never paste the private key into chat. Have them paste it into Prodpeek directly.

## Grant exactly these permissions

- `A dedicated unix user, not root` — The menu decides which commands run; the unix account decides what those commands can see. A low-privilege user is the third layer.
- `Membership of the docker group, only if you need the docker tools` — docker_ps, docker_logs and docker_inspect_mounts need it. Be aware this is effectively root-equivalent on most hosts — skip it if you do not need them.
- `systemd-journal group, for journal_tail on other units` — Without it the user sees only its own journal entries.

## Refuse these, and say why if the user asks for them

- `root, or passwordless sudo` — Nothing in the menu needs it, and it removes the only layer that is not ours. If a command needs root, that is a reason to review the command.
- `A key you use for anything else` — Generate a new keypair for this. Revoking it should cost you nothing.
- `Password authentication, if you can avoid it` — Supported, but a key is easier to revoke and cannot be guessed.

## Verify before the credential is used

- ssh diag@host id  →  not uid 0, and no unexpected groups.
- sudo -n true as that user must fail.
- In Prodpeek, Test connection lists the menu without touching the host.

## Then, in Prodpeek

1. Services → Add a service → choose the profile `ssh/diagnostics-read`.
2. Connection kind `ssh`, URL `diag@host.example.com:22`.
3. Paste the credential. It is encrypted in the store and never shown again.
4. Run **Test connection**. It lists every tool the upstream advertises and how the
   profile classifies each one. Anything under "not in the policy" is denied by
   default — report that list rather than assuming it is fine.

## Full human walkthrough

## Read-only SSH does not exist; a reviewed command menu does

There is no SSH permission that means "read-only". So Prodpeek ships an adapter
whose entire surface is a fixed list of named commands — `df -hP`, `journalctl -u
<unit> -n <lines>`, `docker logs --tail`, and so on — each a hardcoded argv template
with validated arguments. There is no `run_command`, and the profile records that
refusal explicitly rather than leaving it implied by absence.

Three layers, honestly labelled: the adapter validates and builds the command, the
gateway enforces the same constraints independently before the call reaches it, and
the unix account bounds what those commands can see. The third one is yours to set
up, and it is why this recipe is mostly about the user rather than the key.

## Steps

1. On the host, create a dedicated user:

   ```bash
   sudo adduser --disabled-password --gecos "" diag
   ```

2. On your machine, generate a keypair used for nothing else:

   ```bash
   ssh-keygen -t ed25519 -C "prodpeek" -f ~/.ssh/prodpeek_diag
   ```

3. Install the public key:

   ```bash
   sudo -u diag mkdir -p /home/diag/.ssh
   sudo -u diag tee -a /home/diag/.ssh/authorized_keys < ~/.ssh/prodpeek_diag.pub
   sudo -u diag chmod 700 /home/diag/.ssh
   sudo -u diag chmod 600 /home/diag/.ssh/authorized_keys
   ```

4. Add groups only if you need the tools that require them:

   ```bash
   sudo usermod -aG systemd-journal diag     # journal_tail beyond own units
   sudo usermod -aG docker diag              # docker_* tools — see the warning above
   ```

5. In Prodpeek: **Services → Add a service → SSH host**, URL `diag@your-host:22`,
   and paste the **private** key (`~/.ssh/prodpeek_diag`, the file without `.pub`).

## If the host rate-limits SSH

A `ufw limit` rule on 22/tcp allows six new connections per thirty seconds per
source. Prodpeek reuses one authenticated connection per target and opens a new
session per command, so a run of checks no longer trips it — and if something does
get refused, the error says so rather than looking like a dead host.

The cost of that reuse: a pooled connection stays usable for up to
`PRODPEEK_SSH_POOL_TTL` (300s by default) after you revoke the key. Lower it if that
window matters to you.