Migration: consolidate Echo6 docs to cortex with full infrastructure cleanup sync
- Documents recent infrastructure cleanup (8 CTs destroyed, 35 DNS records removed, Headscale cleanup) - Adds 24 new runbooks covering Authentik, PeerTube, Meshtastic, RECON, Proxmox, Mailcow, Internet Archive, GPU routing - Adds project documentation for headscale, vaultwarden, peertube, matrix, mmud, advbbs, arr stack - Updates services.md, environment.md, caddy.md, authentik.md to match live infrastructure - Removes 4 deprecated runbook duplicates (canonical versions live in projects/) - Adds .gitignore for binary archives and editor temp files Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
parent
89834796ff
commit
e9231ac24a
93 changed files with 51223 additions and 254 deletions
299
runbooks/idahomesh-vpn-device-setup.md
Normal file
299
runbooks/idahomesh-vpn-device-setup.md
Normal file
|
|
@ -0,0 +1,299 @@
|
|||
# IdahoMesh VPN — Device Setup
|
||||
|
||||
Join a device to the IdahoMesh tailnet (Meshtastic mesh network VPN).
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
| Item | Value |
|
||||
|------|-------|
|
||||
| Headscale URL | `https://vpn.idahomesh.com` |
|
||||
| Tailnet prefix | 100.100.0.0/16 |
|
||||
| MagicDNS domain | mesh.local |
|
||||
| Supported platforms | Linux (x86/ARM), Windows, macOS, Android, iOS |
|
||||
|
||||
### Users
|
||||
|
||||
| User | Purpose | Key type |
|
||||
|------|---------|----------|
|
||||
| malice | Echo6 infrastructure (bridge LXC) | Short-lived, single-use |
|
||||
| sidpatchy | Sidpatchy's devices | Short-lived, single-use |
|
||||
| nebra | Nebra CM3 gateways (field devices) | Long-lived, reusable |
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before starting, you need:
|
||||
|
||||
1. **A preauthkey** — generated by the IdahoMesh Headscale admin (see [Generating Keys](#generating-preauthkeys) below)
|
||||
2. **Internet access** on the device (to reach vpn.idahomesh.com)
|
||||
3. **Root/admin access** on the device
|
||||
|
||||
---
|
||||
|
||||
## Linux (Debian/Ubuntu/Raspberry Pi OS)
|
||||
|
||||
### Install Tailscale
|
||||
|
||||
```bash
|
||||
curl -fsSL https://tailscale.com/install.sh | sh
|
||||
```
|
||||
|
||||
### Join the IdahoMesh tailnet
|
||||
|
||||
```bash
|
||||
tailscale up \
|
||||
--login-server=https://vpn.idahomesh.com \
|
||||
--authkey=<YOUR_PREAUTHKEY> \
|
||||
--hostname=<DEVICE_NAME>
|
||||
```
|
||||
|
||||
Replace:
|
||||
- `<YOUR_PREAUTHKEY>` — the key provided to you
|
||||
- `<DEVICE_NAME>` — short, lowercase hostname (e.g., `burley-butte`, `sid-laptop`)
|
||||
|
||||
### Verify
|
||||
|
||||
```bash
|
||||
tailscale status
|
||||
tailscale ip -4
|
||||
ping -c 3 100.100.0.1 # Ping another node on the tailnet
|
||||
```
|
||||
|
||||
You should see a `100.100.x.x` IP assigned.
|
||||
|
||||
---
|
||||
|
||||
## Nebra CM3 Gateway (ARM/Raspberry Pi)
|
||||
|
||||
Same as Linux above. The install script auto-detects ARM.
|
||||
|
||||
```bash
|
||||
# Install
|
||||
curl -fsSL https://tailscale.com/install.sh | sh
|
||||
|
||||
# Join — use the reusable nebra preauthkey
|
||||
tailscale up \
|
||||
--login-server=https://vpn.idahomesh.com \
|
||||
--authkey=<NEBRA_PREAUTHKEY> \
|
||||
--hostname=<GATEWAY_NAME>
|
||||
```
|
||||
|
||||
**Naming convention for Nebra gateways:**
|
||||
|
||||
| Gateway | Hostname |
|
||||
|---------|----------|
|
||||
| Burley Butte | `burley-butte` |
|
||||
| Picabo | `picabo` |
|
||||
| AIDA-NEBRA | `aida-nebra` |
|
||||
|
||||
### Enable Tailscale on boot
|
||||
|
||||
Tailscale installs as a systemd service and starts on boot automatically. Confirm:
|
||||
|
||||
```bash
|
||||
systemctl is-enabled tailscaled
|
||||
# Should output: enabled
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Windows
|
||||
|
||||
### Install
|
||||
|
||||
Download and install Tailscale from: https://tailscale.com/download/windows
|
||||
|
||||
### Join
|
||||
|
||||
Open **PowerShell as Administrator:**
|
||||
|
||||
```powershell
|
||||
tailscale up --login-server=https://vpn.idahomesh.com `
|
||||
--authkey=<YOUR_PREAUTHKEY> `
|
||||
--hostname=<DEVICE_NAME>
|
||||
```
|
||||
|
||||
### Verify
|
||||
|
||||
```powershell
|
||||
tailscale status
|
||||
tailscale ip -4
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## macOS
|
||||
|
||||
### Install
|
||||
|
||||
Download and install Tailscale from: https://tailscale.com/download/mac
|
||||
|
||||
Or via Homebrew:
|
||||
|
||||
```bash
|
||||
brew install tailscale
|
||||
```
|
||||
|
||||
### Join
|
||||
|
||||
```bash
|
||||
tailscale up \
|
||||
--login-server=https://vpn.idahomesh.com \
|
||||
--authkey=<YOUR_PREAUTHKEY> \
|
||||
--hostname=<DEVICE_NAME>
|
||||
```
|
||||
|
||||
### Verify
|
||||
|
||||
```bash
|
||||
tailscale status
|
||||
tailscale ip -4
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Android
|
||||
|
||||
1. Install Tailscale from **F-Droid** (recommended — supports custom servers) or Google Play
|
||||
2. Open Tailscale → tap the three-dot menu → **Use custom coordination server**
|
||||
3. Enter: `https://vpn.idahomesh.com`
|
||||
4. Authenticate (it will open a browser if no authkey is used)
|
||||
|
||||
> **Note:** The Google Play version may not support custom coordination servers. Use the F-Droid build if the option is missing.
|
||||
|
||||
---
|
||||
|
||||
## iOS
|
||||
|
||||
1. Install Tailscale from the App Store
|
||||
2. Open Tailscale → Settings → **Use Alternate Server**
|
||||
3. Enter: `https://vpn.idahomesh.com`
|
||||
4. Authenticate via browser
|
||||
|
||||
> **Note:** iOS support for custom Headscale servers can be limited. If the option is unavailable, use the CLI on another device and share connectivity via subnet routing.
|
||||
|
||||
---
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
Run from the newly joined device:
|
||||
|
||||
```bash
|
||||
echo "=== IdahoMesh VPN Check ==="
|
||||
echo "Hostname: $(hostname)"
|
||||
echo "Tailscale IP: $(tailscale ip -4 2>/dev/null || echo 'N/A')"
|
||||
echo "Status: $(tailscale status --self 2>/dev/null | head -1 || echo 'NOT CONNECTED')"
|
||||
echo "Login server: $(tailscale debug prefs 2>/dev/null | grep -o 'ControlURL:[^ ]*' || echo 'unknown')"
|
||||
```
|
||||
|
||||
Expected: a `100.100.x.x` IP and connected status.
|
||||
|
||||
### Test connectivity to other nodes
|
||||
|
||||
```bash
|
||||
# List all visible peers
|
||||
tailscale status
|
||||
|
||||
# Ping another node by MagicDNS name
|
||||
tailscale ping <OTHER_HOSTNAME>
|
||||
|
||||
# Or by IP
|
||||
ping 100.100.0.x
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Generating Preauthkeys
|
||||
|
||||
**Admin only** — run on the IdahoMesh Headscale server (CT 106, 192.168.1.106):
|
||||
|
||||
```bash
|
||||
# For a human user (single-use, expires in 24h)
|
||||
headscale preauthkeys create --user <USERNAME> --expiration 24h
|
||||
|
||||
# For a human user (single-use, longer window)
|
||||
headscale preauthkeys create --user <USERNAME> --expiration 72h
|
||||
|
||||
# For Nebra gateways (reusable, long-lived)
|
||||
headscale preauthkeys create --user nebra --reusable --expiration 8760h
|
||||
|
||||
# List existing keys
|
||||
headscale preauthkeys list --user <USERNAME>
|
||||
```
|
||||
|
||||
Users: `malice` (ID 4), `sidpatchy` (ID 2), `nebra` (ID 3)
|
||||
|
||||
> **Note:** Headscale v0.28.0 `--user` flag requires user IDs (integers), not names.
|
||||
|
||||
---
|
||||
|
||||
## Removing a Device
|
||||
|
||||
**Admin only:**
|
||||
|
||||
```bash
|
||||
# List all nodes
|
||||
headscale nodes list
|
||||
|
||||
# Delete a node by ID
|
||||
headscale nodes delete -i <NODE_ID>
|
||||
```
|
||||
|
||||
On the device itself:
|
||||
|
||||
```bash
|
||||
tailscale logout
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "connection refused" or timeout on join
|
||||
|
||||
- Confirm the device has internet access: `curl -I https://vpn.idahomesh.com`
|
||||
- Check DNS resolution: `dig vpn.idahomesh.com`
|
||||
- Verify the preauthkey hasn't expired
|
||||
|
||||
### "key expired" or "invalid key"
|
||||
|
||||
- Preauthkeys are time-limited. Ask the admin for a new one
|
||||
- Nebra keys are reusable but still expire — check with `headscale preauthkeys list --user nebra`
|
||||
|
||||
### Device shows "offline" in node list
|
||||
|
||||
- Check if tailscaled is running: `systemctl status tailscaled`
|
||||
- Restart: `systemctl restart tailscaled`
|
||||
- Force re-auth: `tailscale up --login-server=https://vpn.idahomesh.com --force-reauth`
|
||||
|
||||
### Can't reach other nodes
|
||||
|
||||
- Confirm both devices show as "online" in `tailscale status`
|
||||
- Check ACL policy — the admin may need to add rules for your user group
|
||||
- Try direct IP ping before MagicDNS names
|
||||
|
||||
### MagicDNS not resolving
|
||||
|
||||
- Confirm `--accept-dns=true` (this is the default)
|
||||
- Check: `tailscale debug prefs | grep CorpDNS`
|
||||
- Restart tailscaled
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Item | Value |
|
||||
|------|-------|
|
||||
| Headscale URL | `https://vpn.idahomesh.com` |
|
||||
| Tailnet prefix | 100.100.0.0/16 |
|
||||
| MagicDNS domain | mesh.local |
|
||||
| Headscale server | CT 106 on utility (192.168.1.106) |
|
||||
| Admin access | SSH to 192.168.1.106 or via utility Proxmox |
|
||||
| ACL policy | `/etc/headscale/acl.json` on CT 106 |
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2026-02-11*
|
||||
Loading…
Add table
Add a link
Reference in a new issue