Vish/homelab-optimized

Fork 0

Files

Gitea Mirror Bot 7cee5297c1

Documentation / Build Docusaurus (push) Failing after 7s

Details

Documentation / Deploy to GitHub Pages (push) Has been skipped

Details

Sanitized mirror from private repository - 2026-03-09 11:59:35 UTC

2026-03-09 11:59:35 +00:00

14 KiB

Raw Blame History

🌐 Tailscale Setup Guide with Split-Brain DNS

🟡 Intermediate Guide

This guide shows you how to set up Tailscale for secure homelab access with split-brain DNS, allowing you to use local hostnames like atlantis.vish.local from anywhere in the world.

🎯 Why Tailscale Over Traditional VPN?

✅ Advantages of Tailscale

Zero-config mesh networking - No complex server setup
NAT traversal - Works behind any router/firewall
Split-brain DNS - Use local hostnames anywhere
Per-device access control - Granular permissions
Cross-platform - Works on everything
No port forwarding needed - Completely eliminates router configuration

🆚 Tailscale vs WireGuard

Feature	Tailscale	Traditional WireGuard
Setup Complexity	🟢 Simple	🟡 Moderate
NAT Traversal	🟢 Automatic	🔴 Manual
DNS Resolution	🟢 Built-in	🟡 Manual setup
Device Management	🟢 Web dashboard	🔴 Config files
Port Forwarding	🟢 Not needed	🔴 Required

🏗️ Your Homelab Hosts

Here are all the hosts that will be accessible via Tailscale:

🖥️ Primary Infrastructure

Hostname	IP Range	Role	Key Services
`atlantis.vish.local`	192.168.1.x	Primary NAS	Plex, Vaultwarden, Grafana, GitLab
`calypso.vish.local`	192.168.1.x	Media NAS	Immich, Arr Suite, Prometheus
`concord-nuc.vish.local`	192.168.1.x	Edge Computing	Home Assistant, WireGuard, Invidious

🖥️ Virtual Machines

Hostname	IP Range	Role	Key Services
`homelab-vm.vish.local`	192.168.1.x	General VM	Satisfactory, Mattermost, Signal API
`chicago-vm.vish.local`	192.168.1.x	Gaming VM	Jellyfin, Factorio, Neko
`bulgaria-vm.vish.local`	192.168.1.x	Utility VM	Navidrome, Droppy, Syncthing

🔧 Specialized Hosts

Hostname	IP Range	Role	Key Services
`anubis.vish.local`	192.168.1.x	Archive/Backup	ArchiveBox, PhotoPrism, Matrix Conduit
`guava.vish.local`	192.168.1.x	Remote Server	Ollama, CoCalc, OpenWebUI
`setillo.vish.local`	192.168.1.x	Monitoring	Prometheus, AdGuard

🍓 Raspberry Pi Cluster

Hostname	IP Range	Role	Key Services
`rpi-vish.vish.local`	192.168.1.x	IoT Hub	Immich, DNS Updater
`rpi-kevin.vish.local`	192.168.1.x	Game Server	Minecraft, PMC

🎮 Edge Devices

Hostname	IP Range	Role	Key Services
`nvidia-shield.vish.local`	192.168.1.x	Media Client	WireGuard Client
`contabo-vm.vish.local`	External	Cloud VM	Ollama, External Services

🚀 Quick Setup (5 Minutes)

1. Create Tailscale Account

# Visit https://tailscale.com and create account
# Choose the free plan (up to 20 devices, 3 users)

2. Install on Each Host

Ubuntu/Debian (Most VMs)

# Add Tailscale repository
curl -fsSL https://tailscale.com/install.sh | sh

# Start Tailscale
sudo tailscale up

# Follow the authentication URL

Synology NAS (Atlantis, Calypso)

# Method 1: Package Center
# Search for "Tailscale" and install

# Method 2: Docker (if package not available)
docker run -d \
  --name=tailscale \
  --cap-add=NET_ADMIN \
  --cap-add=SYS_MODULE \
  --device=/dev/net/tun \
  -v /var/lib/tailscale:/var/lib/tailscale \
  -v /dev/net/tun:/dev/net/tun \
  tailscale/tailscale:latest \
  tailscaled

Raspberry Pi

# Same as Ubuntu/Debian
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

3. Install on Client Devices

Windows/Mac: Download from https://tailscale.com/download
iOS/Android: Install from app store
Linux Desktop: Same as server installation

🌐 Split-Brain DNS Configuration

Current Production Configuration

Based on your live Tailscale setup, here's your working DNS configuration:

Tailnet DNS Name: `tail.vish.gg`

Unique identifier for your Tailscale network
Used for DNS entries, device sharing, and TLS certificates
Automatically assigned by Tailscale

Nameserver Configuration:

# MagicDNS (Primary)
tail.vish.gg → 100.100.100.100

# Split DNS for Local Network
vish.local → 192.168.0.250 (Use with exit mode)

# Global Nameservers (Your Homelab DNS)
100.103.48.78  # Calypso Tailscale IP
100.72.55.21   # Concord-NUC Tailscale IP

Search Domains: `tail.vish.gg`

Automatically appends to short hostnames
Enables atlantis → atlantis.tail.vish.gg resolution

1. Enable MagicDNS ✅ Already Configured

# Your MagicDNS is already enabled with:
# - Tailnet domain: tail.vish.gg
# - Primary DNS: 100.100.100.100 (MagicDNS)
# - Override DNS servers: ENABLED
# - Apps control: Enabled for third-party app access

2. Add Custom DNS Records

In the Tailscale admin console, add these DNS records:

A Records (IPv4)

atlantis.vish.local     → 192.168.1.100  # Replace with actual IP
calypso.vish.local      → 192.168.1.101
concord-nuc.vish.local  → 192.168.1.102
homelab-vm.vish.local   → 192.168.1.103
chicago-vm.vish.local   → 192.168.1.104
bulgaria-vm.vish.local  → 192.168.1.105
anubis.vish.local       → 192.168.1.106
guava.vish.local        → 192.168.1.107
setillo.vish.local      → 192.168.1.108
rpi-vish.vish.local     → 192.168.1.109
rpi-kevin.vish.local    → 192.168.1.110
nvidia-shield.vish.local → 192.168.1.111

CNAME Records (Aliases)

# Service-specific aliases
plex.vish.local         → atlantis.vish.local
grafana.vish.local      → atlantis.vish.local
immich.vish.local       → calypso.vish.local
homeassistant.vish.local → concord-nuc.vish.local
jellyfin.vish.local     → chicago-vm.vish.local

3. Alternative: Local DNS Server Method

If you prefer more control, set up a local DNS server:

Pi-hole Configuration (on Atlantis)

# Add to Pi-hole custom DNS records
# /etc/pihole/custom.list
192.168.1.100 atlantis.vish.local
192.168.1.101 calypso.vish.local
192.168.1.102 concord-nuc.vish.local
# ... add all hosts

Tailscale DNS Settings

# Point Tailscale to use your Pi-hole
# In admin console: DNS → Nameservers
# Add: 192.168.1.100 (Pi-hole IP)

🔧 Advanced Configuration

1. Subnet Routing (Access entire homelab network)

On your primary router/gateway host (e.g., Atlantis):

# Enable subnet routing
sudo tailscale up --advertise-routes=192.168.1.0/24

# In Tailscale admin console:
# Go to Machines → atlantis → Route settings
# Enable the advertised route

2. Exit Node (Route all traffic through homelab)

# On a homelab host (e.g., Atlantis)
sudo tailscale up --advertise-exit-node

# On client devices
tailscale up --exit-node=atlantis

3. Access Control Lists (ACLs)

Create fine-grained access control:

{
  "acls": [
    {
      "action": "accept",
      "src": ["group:family"],
      "dst": ["192.168.1.0/24:*"]
    },
    {
      "action": "accept", 
      "src": ["group:admin"],
      "dst": ["*:*"]
    }
  ],
  "groups": {
    "group:family": ["user1@example.com", "user2@example.com"],
    "group:admin": ["admin@example.com"]
  }
}

📱 Client Usage Examples

From Your Phone

# Access services using local hostnames
https://atlantis.vish.local:8920  # Plex
https://grafana.vish.local:3000   # Grafana
https://immich.vish.local         # Photo management

From Laptop While Traveling

# SSH to any host
ssh user@atlantis.vish.local
ssh user@homelab-vm.vish.local

# Access web services
curl http://atlantis.vish.local:8080

Service Discovery

# List all Tailscale devices
tailscale status

# Ping any host
ping atlantis.vish.local
ping calypso.vish.local

🛡️ Security Best Practices

1. Device Authentication

# Require device approval
# In admin console: Settings → Device approval
# Enable "Device approval required"

2. Key Expiry

# Set key expiration (default 180 days)
# In admin console: Settings → Key expiry
# Recommended: 90 days for better security

3. Disable Key Expiry for Servers

# For always-on servers, disable expiry
sudo tailscale up --auth-key=tskey-xxx --advertise-routes=192.168.1.0/24

4. Network Segmentation

# Use ACLs to limit access between devices
# Example: Only allow admin devices to access management interfaces

🔍 Troubleshooting

DNS Not Resolving

# Check MagicDNS status
tailscale status --json | jq '.MagicDNSSuffix'

# Test DNS resolution
nslookup atlantis.vish.local
dig atlantis.vish.local

# Force DNS refresh
sudo tailscale up --reset

Can't Access Local Services

# Check if subnet routing is enabled
tailscale status | grep "subnet routes"

# Verify routes in admin console
# Machines → [host] → Route settings

# Test connectivity
ping 192.168.1.100
telnet atlantis.vish.local 8080

Connection Issues

# Check Tailscale status
tailscale status

# View logs
sudo journalctl -u tailscaled -f

# Restart Tailscale
sudo systemctl restart tailscaled

📊 Service Access Map

Once configured, you can access services like this:

Media Services

# Plex Media Server
https://atlantis.vish.local:32400

# Immich Photos
https://calypso.vish.local:2283

# Jellyfin
https://chicago-vm.vish.local:8096

# Navidrome Music
https://bulgaria-vm.vish.local:4533

Management & Monitoring

# Grafana Dashboards
https://atlantis.vish.local:3000

# Prometheus Metrics
https://calypso.vish.local:9090

# Uptime Kuma
https://atlantis.vish.local:3001

# Portainer
https://atlantis.vish.local:9000

Development & Productivity

# GitLab
https://atlantis.vish.local:8929

# Vaultwarden (Password Manager)
https://atlantis.vish.local:8222

# Home Assistant
https://concord-nuc.vish.local:8123

# Mattermost Chat
https://homelab-vm.vish.local:8065

🚀 Migration from WireGuard

If you're currently using WireGuard:

1. Parallel Setup

# Keep WireGuard running while testing Tailscale
# Both can coexist temporarily

2. Test All Services

# Verify each service works via Tailscale
# Test from multiple client devices

3. Update Documentation

# Update service URLs in documentation
# Change from external IPs to .vish.local hostnames

4. Decommission WireGuard

# Once confident, disable WireGuard
# Remove port forwarding rules
# Keep configs as backup

💡 Pro Tips

1. Use Descriptive Hostnames

# Instead of generic names, use descriptive ones
media-server.vish.local    # Instead of atlantis.vish.local
monitoring.vish.local      # For Grafana/Prometheus host
gaming.vish.local          # For game servers

2. Create Service-Specific Aliases

# Add CNAME records for easy access
plex.vish.local → atlantis.vish.local
photos.vish.local → calypso.vish.local
chat.vish.local → homelab-vm.vish.local

3. Mobile Shortcuts

# Create bookmarks/shortcuts on mobile devices
# Use descriptive names: "Home Plex", "Photo Library", etc.

4. Monitoring Integration

# Update Uptime Kuma to monitor .vish.local hostnames
# Update Grafana dashboards to use local hostnames
# Configure alerts to use Tailscale IPs

🔗 Integration with Existing Services

Update Service Configurations

Many services can be updated to use Tailscale hostnames:

# Example: Update docker-compose.yml files
environment:
  - GRAFANA_URL=https://grafana.vish.local:3000
  - PLEX_URL=https://plex.vish.local:32400
  - DATABASE_HOST=atlantis.vish.local

Reverse Proxy Updates

# Update Nginx Proxy Manager
# Change upstream servers to use .vish.local hostnames
upstream plex {
    server atlantis.vish.local:32400;
}

📋 Quick Reference

Essential Commands

# Check status
tailscale status

# Connect/disconnect
tailscale up
tailscale down

# List devices
tailscale status --peers

# Get IP address
tailscale ip -4

# Enable/disable routes
tailscale up --advertise-routes=192.168.1.0/24

Common URLs After Setup

# Admin interfaces
https://atlantis.vish.local:9000      # Portainer
https://atlantis.vish.local:3000      # Grafana
https://atlantis.vish.local:3001      # Uptime Kuma

# Media services  
https://atlantis.vish.local:32400     # Plex
https://calypso.vish.local:2283       # Immich
https://chicago-vm.vish.local:8096    # Jellyfin

# Communication
https://homelab-vm.vish.local:8065    # Mattermost
https://atlantis.vish.local:8080      # Signal API

📱 Mobile Device Setup - NEW! iOS, Android, macOS, Linux Tailscale configuration
👨‍👩‍👧‍👦 Family Network Integration - NEW! Connect family's separate network via Tailscale
💻 Laptop Travel Setup - Secure travel with VPN tunneling
Port Forwarding Guide - Traditional VPN setup (alternative)
🔥 Disaster Recovery Guide - Router failure and network reconfiguration
🔐 Offline Password Access - Accessing passwords when services are down
Security Model - Overall security architecture
Network Architecture - Network topology and design
Individual Service Docs - Service-specific access information

🎉 Result: After setup, you can access your entire homelab using friendly hostnames like atlantis.vish.local from anywhere in the world, without any port forwarding or complex VPN configuration!

14 KiB Raw Blame History