227 lines
4.6 KiB
Markdown
227 lines
4.6 KiB
Markdown
# Headscale Setup & Connection Guide
|
|
|
|
> Generated: 2025-11-11
|
|
> Server: tower-of-joy
|
|
> Network Range: 10.99.0.0/16
|
|
|
|
## Service Status
|
|
|
|
✅ **Headscale is running**
|
|
- Container: `headscale`
|
|
- Web/API Port: `8085`
|
|
- Metrics Port: `9090`
|
|
- Server URL: `http://192.168.86.149:8085`
|
|
|
|
## User & Authentication
|
|
|
|
**User Created:** `homelab` (ID: 1)
|
|
|
|
**Pre-Auth Key (expires in 30 days, reusable):**
|
|
```
|
|
b4c17f9e9f01ea2e54b24e0369e2949bd28bfaf46944c634
|
|
```
|
|
|
|
⚠️ **Security Note:** This key allows devices to join your mesh network. Keep it secure and regenerate after use if needed.
|
|
|
|
---
|
|
|
|
## Connecting This Server (tower-of-joy)
|
|
|
|
### Step 1: Install Tailscale Client
|
|
|
|
```bash
|
|
curl -fsSL https://tailscale.com/install.sh | sh
|
|
```
|
|
|
|
### Step 2: Connect to Headscale
|
|
|
|
```bash
|
|
sudo tailscale up --login-server=http://192.168.86.149:8085 \
|
|
--authkey=b4c17f9e9f01ea2e54b24e0369e2949bd28bfaf46944c634 \
|
|
--accept-routes
|
|
```
|
|
|
|
### Step 3: Verify Connection
|
|
|
|
```bash
|
|
# Check Tailscale status
|
|
sudo tailscale status
|
|
|
|
# Get your mesh IP (should be in 10.99.x.x range)
|
|
sudo tailscale ip -4
|
|
|
|
# Test connectivity
|
|
ping $(tailscale ip -4)
|
|
```
|
|
|
|
---
|
|
|
|
## Connecting Other Devices (Laptop, Phone, etc.)
|
|
|
|
### On Linux/macOS
|
|
|
|
```bash
|
|
# Install Tailscale
|
|
curl -fsSL https://tailscale.com/install.sh | sh
|
|
|
|
# Connect to your Headscale server
|
|
sudo tailscale up --login-server=http://192.168.86.149:8085 \
|
|
--authkey=b4c17f9e9f01ea2e54b24e0369e2949bd28bfaf46944c634
|
|
```
|
|
|
|
### On Windows
|
|
|
|
1. Download Tailscale from https://tailscale.com/download/windows
|
|
2. Install and open Tailscale
|
|
3. Run in PowerShell (as Administrator):
|
|
```powershell
|
|
tailscale up --login-server=http://192.168.86.149:8085 `
|
|
--authkey=b4c17f9e9f01ea2e54b24e0369e2949bd28bfaf46944c634
|
|
```
|
|
|
|
### On Android/iOS
|
|
|
|
1. Install Tailscale app from app store
|
|
2. Open app settings
|
|
3. Set "Control URL" to: `http://192.168.86.149:8085`
|
|
4. Use auth key: `b4c17f9e9f01ea2e54b24e0369e2949bd28bfaf46944c634`
|
|
|
|
---
|
|
|
|
## Testing Remote SSH Access
|
|
|
|
Once devices are connected to the mesh:
|
|
|
|
```bash
|
|
# From your laptop (after connecting to Headscale)
|
|
|
|
# Get tower-of-joy's mesh IP
|
|
ssh jpmschweitzer@<tower-mesh-ip>
|
|
|
|
# Example (your actual IP will be something like 10.99.0.1)
|
|
ssh jpmschweitzer@10.99.0.1
|
|
```
|
|
|
|
**Benefits:**
|
|
- No port forwarding needed
|
|
- No exposing SSH to internet
|
|
- Encrypted peer-to-peer connections
|
|
- Works from anywhere
|
|
|
|
---
|
|
|
|
## Headscale Management Commands
|
|
|
|
### List All Connected Devices
|
|
```bash
|
|
docker exec headscale headscale nodes list
|
|
```
|
|
|
|
### List Users
|
|
```bash
|
|
docker exec headscale headscale users list
|
|
```
|
|
|
|
### Generate New Pre-Auth Key
|
|
```bash
|
|
# 7 days, single-use
|
|
docker exec headscale headscale preauthkeys create --user 1 --expiration 168h
|
|
|
|
# 30 days, reusable
|
|
docker exec headscale headscale preauthkeys create --user 1 --expiration 720h --reusable
|
|
```
|
|
|
|
### List Pre-Auth Keys
|
|
```bash
|
|
docker exec headscale headscale preauthkeys list --user 1
|
|
```
|
|
|
|
### Remove a Device
|
|
```bash
|
|
# First, get the node ID
|
|
docker exec headscale headscale nodes list
|
|
|
|
# Then delete by ID
|
|
docker exec headscale headscale nodes delete <node-id>
|
|
```
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Can't Connect to Headscale Server
|
|
|
|
1. **Check if Headscale is running:**
|
|
```bash
|
|
docker ps | grep headscale
|
|
```
|
|
|
|
2. **Check firewall (if connecting from external network):**
|
|
```bash
|
|
sudo ufw status
|
|
# If needed: sudo ufw allow 8085/tcp
|
|
```
|
|
|
|
3. **View Headscale logs:**
|
|
```bash
|
|
docker logs headscale --tail 50
|
|
```
|
|
|
|
### Devices Can't See Each Other
|
|
|
|
1. **Check device is registered:**
|
|
```bash
|
|
docker exec headscale headscale nodes list
|
|
```
|
|
|
|
2. **Verify IPs are in the 10.99.0.0/16 range:**
|
|
```bash
|
|
sudo tailscale ip -4
|
|
```
|
|
|
|
3. **Test direct ping:**
|
|
```bash
|
|
ping <other-device-mesh-ip>
|
|
```
|
|
|
|
### Need to Regenerate Keys
|
|
|
|
```bash
|
|
# Create new auth key
|
|
docker exec headscale headscale preauthkeys create --user 1 --expiration 720h --reusable
|
|
|
|
# Update this document with the new key
|
|
```
|
|
|
|
---
|
|
|
|
## Configuration File Location
|
|
|
|
**Config:** `/home/jpmschweitzer/docker-data/headscale/config/config.yaml`
|
|
**Database:** `/home/jpmschweitzer/docker-data/headscale/data/db.sqlite`
|
|
|
|
To edit configuration:
|
|
1. Edit the config file
|
|
2. Restart container: `docker restart headscale`
|
|
3. Verify: `docker logs headscale --tail 20`
|
|
|
|
---
|
|
|
|
## Next Steps After Setup
|
|
|
|
1. ✅ Connect tower-of-joy to Headscale
|
|
2. ✅ Connect your laptop/work devices
|
|
3. ✅ Test SSH access from laptop to server
|
|
4. ✅ Configure SSH key authentication for security
|
|
5. ⚡ Add phone/tablet for remote monitoring
|
|
6. ⚡ Set up exit node (optional - route all traffic through home)
|
|
|
|
---
|
|
|
|
## Resources
|
|
|
|
- **Headscale Docs:** https://headscale.net/
|
|
- **Tailscale Client Docs:** https://tailscale.com/kb/
|
|
- **Container Logs:** `docker logs headscale -f`
|
|
- **Portainer:** http://192.168.86.149:8001
|