9ff12700ae
Scaffold for troubleshooting MakerFLOSS hosts at the makerspace. Reference + thin runbooks model — authoritative data stays in the source repos (AnsibleBaobabV4, MakerFLOSS_Mikrotik, MakerFLOSS). - access.md: reach paths for mamba-on-LAN and fisi-tunneling-in (netbird on-demand, VPS bastion, ProxyJump via kuku->mamba), with the isolation rule. - network-map.md: subnet pointers + open question on makerspace addressing (10.2.30/172.17.3/10.0.0). - runbooks/switch-crs310.md: CRS310 connectivity + lockout recovery. - incidents/: dated log scaffold. - CLAUDE.md: operating rules for this repo. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
157 lines
6.6 KiB
Markdown
157 lines
6.6 KiB
Markdown
# Access — reaching MakerFLOSS / makerspace hosts
|
||
|
||
How to get a shell on the hosts we troubleshoot, from each place you might be
|
||
working. **Read the section that matches your situation.**
|
||
|
||
There are two actors:
|
||
- **You (sjat)** — at the makerspace with **mamba** (laptop), or elsewhere.
|
||
- **Claude** — lives on **fisi** (homelab) and must *tunnel in* to help at the
|
||
makerspace.
|
||
|
||
---
|
||
|
||
## The hosts and where they live
|
||
|
||
| Host | Address | SSH | Where it sits | Notes |
|
||
|------|---------|-----|---------------|-------|
|
||
| **makerfloss VPS** | `88.99.32.236` / `makerfloss.eu` | `:7576` | Public (Hetzner) | Public entrypoint + bastion. Forgejo on `:7577`. WG `wg1` hub `10.13.0.1`. Netbird control plane `nb.makerfloss.eu`. |
|
||
| **makerfloss1** | `172.17.3.51` | `:7576` | Makerspace LAN | Local Docker/dev host. `wg1` peer `10.13.0.2` (full-tunnel). |
|
||
| **mf04** | `10.0.0.184` | `:7576` | Makerspace LAN | Testmachine. `wg1` peer `10.13.0.3` (split-tunnel). Netbird peer. |
|
||
| **crs310-maker** (switch) | mgmt `192.168.88.1` | `:22` | Makerspace, port `ether8` only | Mgmt VLAN 99, isolated. Data VLAN 30 = `10.2.30.0/24`. See [runbooks/switch-crs310.md](runbooks/switch-crs310.md). |
|
||
| **fisi** (home) | `10.20.10.17` | `:7576` | Homelab | Where Claude runs. Behind OPNsense; baobab WG hub is **kuku** (`10.8.0.1`, UDP 51194). |
|
||
| **mamba** (laptop) | LAN-dependent | `:7576` | Roams | Baobab WG peer `10.8.0.4`; makerfloss `wg1` roaming peer `10.13.0.5`; Netbird peer. |
|
||
|
||
> The makerspace addressing is **not fully pinned** — see the open question in
|
||
> [network-map.md](network-map.md). Confirm the host's current IP before relying
|
||
> on the table.
|
||
|
||
---
|
||
|
||
## A. You're at the makerspace with mamba (on the LAN)
|
||
|
||
Easiest case — mamba is directly on the makerspace network.
|
||
|
||
- **The switch (mgmt):** plug mamba into **`ether8`** (mgmt VLAN 99). You get a
|
||
DHCP lease in `192.168.88.10–254`; switch is `192.168.88.1` (SSH, and web UI
|
||
`http://192.168.88.1`). A pinned NetworkManager profile `crs310-bench` /
|
||
static `192.168.88.2` is documented in the Mikrotik repo for this.
|
||
- **The switch (data ports `ether2–7`):** you land on data VLAN 30
|
||
(`10.2.30.0/24`, gateway `.1`) — normal user network, *no* switch mgmt here.
|
||
- **makerfloss1 / mf04:** SSH directly to their LAN IPs (`172.17.3.51`,
|
||
`10.0.0.184`) on `:7576`.
|
||
|
||
For Ansible against the switch from mamba, run from the `MakerFLOSS_Mikrotik`
|
||
repo with mamba on `ether8`.
|
||
|
||
---
|
||
|
||
## B. Claude tunneling in from fisi (no laptop at the makerspace)
|
||
|
||
fisi has **no direct route** to the makerspace LAN. Pick one path. Ordered by
|
||
preference given the **isolation requirement** (keep makerspace and homelab
|
||
apart — see the rule box below).
|
||
|
||
### B1. Netbird overlay — *on-demand only* (primary)
|
||
|
||
fisi is to be enrolled as a peer on the self-hosted Netbird control plane
|
||
(`nb.makerfloss.eu`), but the tunnel is brought **up only when needed and torn
|
||
down after**. This reaches other Netbird peers (mf04, mamba) on the
|
||
`100.92.0.0/16` overlay.
|
||
|
||
One-time enrollment (needs a setup key from the `nb.makerfloss.eu` dashboard):
|
||
|
||
```bash
|
||
# install netbird (Debian) — see netbirdio docs / baobab.netbird_client role
|
||
netbird up --setup-key <KEY> --management-url https://nb.makerfloss.eu
|
||
netbird status # confirm peers Connected
|
||
```
|
||
|
||
Per-session use:
|
||
|
||
```bash
|
||
netbird up # bring the overlay up for this session
|
||
# ... do the work, ssh to peer's 100.x address ...
|
||
netbird down # TEAR DOWN when done — do not leave it up
|
||
```
|
||
|
||
> **Why on-demand:** sjat's explicit constraint — nothing from the makerspace
|
||
> should be able to bleed into fisi/the homelab. Netbird stays **down by
|
||
> default** on fisi; it is not a standing tunnel.
|
||
|
||
### B2. Via the makerfloss VPS bastion (no tunnel on fisi)
|
||
|
||
The cleanest isolation-preserving path: fisi only ever talks to the **public
|
||
VPS**, which hops onward over its own `wg1` tunnel. fisi itself joins no
|
||
makerspace network.
|
||
|
||
```bash
|
||
# Land on the VPS:
|
||
ssh -p 7576 sjat@makerfloss.eu
|
||
|
||
# From the VPS, reach wg1 peers on the makerfloss plane:
|
||
ssh -p 7576 sjat@10.13.0.2 # makerfloss1
|
||
ssh -p 7576 sjat@10.13.0.3 # mf04
|
||
```
|
||
|
||
Or, if/when the per-machine SSH DNAT from the VPN design is in place, jump
|
||
straight through the VPS with a single hop (ports `:7578`/`:7579` → testmachine
|
||
`:7576`). Confirm these DNAT rules exist before relying on them.
|
||
|
||
```bash
|
||
ssh -J sjat@makerfloss.eu:7576 -p 7576 sjat@10.13.0.3 # fisi → VPS → mf04
|
||
```
|
||
|
||
This path does **not** require mamba to be present.
|
||
|
||
### B3. ProxyJump via kuku → mamba (only when mamba is at the makerspace)
|
||
|
||
This is the chain the `AnsibleBaobabV4` inventory already uses for `mf04`:
|
||
|
||
```
|
||
fisi → kuku (baobab WG hub) → mamba (WG peer 10.8.0.4, on the makerspace LAN) → mf04
|
||
```
|
||
|
||
```bash
|
||
ssh -o ProxyJump="kuku,sjat@10.8.0.4:7576" -p 7576 sjat@10.0.0.184 # mf04
|
||
```
|
||
|
||
In `AnsibleBaobabV4/host_vars/mf04.yml`:
|
||
`ansible_ssh_common_args: '-o ProxyJump="kuku,sjat@10.8.0.4:7576"'`.
|
||
|
||
**Constraint:** only works while mamba is physically at the makerspace, online,
|
||
and roaming on the baobab WG plane. Breaks the moment mamba leaves.
|
||
|
||
### Choosing between B1/B2/B3
|
||
|
||
| Need | Use |
|
||
|------|-----|
|
||
| Reach mf04/mamba over the overlay, mamba may be absent | **B1** (netbird, on-demand) |
|
||
| Reach makerfloss1 / mf04 / VPS-side services, max isolation, no tunnel on fisi | **B2** (VPS bastion) |
|
||
| mamba is at the makerspace and you want the existing Ansible path | **B3** (ProxyJump) |
|
||
| The **switch** mgmt plane (`192.168.88.1`) | None of these directly — mgmt VLAN 99 is reachable only from `ether8`. Need a host *on* `ether8` (mamba, or a testmachine patched in) to forward through. See switch runbook. |
|
||
|
||
---
|
||
|
||
## C. Isolation rule (important)
|
||
|
||
> **Keep the makerspace and the homelab apart.** fisi must not hold a standing
|
||
> tunnel into the makerspace. Bring Netbird **up only for the task, down
|
||
> immediately after**. Prefer the VPS-bastion path (B2) when it suffices, since
|
||
> it puts no makerspace network on fisi at all. The concern is preventing any
|
||
> compromise at the makerspace from reaching fisi/the homelab.
|
||
|
||
---
|
||
|
||
## D. Secrets & credentials (where they live — not stored here)
|
||
|
||
- **Ansible vault (baobab):** `~/.ansible/vault-keys/prod.txt`; secrets in
|
||
`AnsibleBaobabV4/group_vars/all/90-secrets.vault.yml`
|
||
(`ansible-vault edit ... --vault-id prod@`). WG/Netbird/service secrets are
|
||
`vault_*` keys there.
|
||
- **Ansible vault (switch):** identity `makerfloss`,
|
||
`~/.ansible/vault-keys/makerfloss.txt`; switch admin password in
|
||
`MakerFLOSS_Mikrotik/group_vars/mikrotik.vault.yml`.
|
||
- **SSH:** operator key `~/.ssh/id_ed25519`; project-wide SSH port is **7576**
|
||
(switch SSH is on `:22`, Forgejo git on `:7577`).
|
||
|
||
Never commit secrets to this repo.
|