# SSH playbook (Linux server ops)

## Defaults and conventions

- Prefer SSH keys (ed25519) and `~/.ssh/config` aliases for repeatable runs.
- Avoid putting passwords in files, prompts, or chat logs. If password auth is required, use an interactive terminal/TTY.
- Start with read-only inspection, then apply changes, then verify.

Recommended env vars for wrappers:

- `REMOTE_USER`: default SSH user
- `REMOTE_PORT`: default SSH port (usually 22)
- `REMOTE_KEY`: path to identity file (private key)
- `REMOTE_CONNECT_TIMEOUT`: connect timeout seconds

## SSH key setup (recommended)

Generate a new key:

```bash
ssh-keygen -t ed25519 -C "codex" -f ~/.ssh/id_ed25519
```

Copy the public key to the server:

```bash
ssh-copy-id -i ~/.ssh/id_ed25519.pub -p 22 USER@SERVER_IP
```

Add a host alias:

```sshconfig
Host my-server
  HostName SERVER_IP
  Port 22
  User USER
  IdentityFile ~/.ssh/id_ed25519
  IdentitiesOnly yes
```

## Common tasks

### Connectivity and OS info

```bash
ssh my-server "whoami && hostname && uname -a"
ssh my-server "cat /etc/os-release"
```

### Disk and memory

```bash
ssh my-server "df -h"
ssh my-server "free -h"
ssh my-server "du -sh /var/log/* | sort -h | tail"
```

### Processes and ports

```bash
ssh my-server "ps aux --sort=-%mem | head"
ssh my-server "ss -lntp"
```

### Logs (systemd)

```bash
ssh my-server "journalctl -u SERVICE -n 200 --no-pager"
ssh my-server "journalctl -u SERVICE -f --no-pager"
```

### Services (systemd)

Status:

```bash
ssh my-server "systemctl status SERVICE --no-pager"
```

Restart (often needs sudo and TTY):

```bash
ssh -tt my-server "sudo systemctl restart SERVICE"
```

Non-interactive sudo (fails if a password prompt would be required):

```bash
ssh my-server "sudo -n systemctl restart SERVICE"
```

## Safer host key handling

- Prefer verifying the host key fingerprint out-of-band on first connect.
- If you must automate first-connect for ephemeral hosts, use `StrictHostKeyChecking=accept-new` (OpenSSH 7.6+).
- If you see a "host key changed" warning, treat it as a potential security incident until you confirm the change is expected.

## Troubleshooting quick hits

- `Permission denied (publickey)`: wrong user, wrong key, server missing your public key, or `sshd` settings.
- `Connection timed out`: routing/firewall/security group, wrong port, server down.
- `No route to host`: network path missing (VPN, subnet, ACL).