Initial commit
This commit is contained in:
Zhongwei Li
468
references/tailscale-integration.md
Normal file
468
references/tailscale-integration.md
Normal file
@@ -0,0 +1,468 @@
|
||||
# Tailscale Integration Guide
|
||||
|
||||
How to use Tailscale SSH with sshsync for secure, zero-config remote access.
|
||||
|
||||
## What is Tailscale?
|
||||
|
||||
Tailscale is a zero-config VPN that creates a secure network between your devices using WireGuard. It provides:
|
||||
|
||||
- **Peer-to-peer encrypted connections**
|
||||
- **No port forwarding required**
|
||||
- **Works across NATs and firewalls**
|
||||
- **MagicDNS for easy device addressing**
|
||||
- **Built-in SSH functionality**
|
||||
- **Access control lists (ACLs)**
|
||||
|
||||
## Why Tailscale + sshsync?
|
||||
|
||||
Combining Tailscale with sshsync gives you:
|
||||
|
||||
1. **Secure connections** everywhere (Tailscale encryption)
|
||||
2. **Simple addressing** (MagicDNS hostnames)
|
||||
3. **Multi-host operations** (sshsync groups and execution)
|
||||
4. **No firewall configuration** needed
|
||||
5. **Works from anywhere** (coffee shop, home, office)
|
||||
|
||||
## Setup
|
||||
|
||||
### 1. Install Tailscale
|
||||
|
||||
**macOS**:
|
||||
```bash
|
||||
brew install tailscale
|
||||
```
|
||||
|
||||
**Linux**:
|
||||
```bash
|
||||
curl -fsSL https://tailscale.com/install.sh | sh
|
||||
```
|
||||
|
||||
**Verify Installation**:
|
||||
```bash
|
||||
tailscale version
|
||||
```
|
||||
|
||||
### 2. Connect to Tailscale
|
||||
|
||||
```bash
|
||||
# Start Tailscale
|
||||
sudo tailscale up
|
||||
|
||||
# Follow the authentication link
|
||||
# This opens browser to authenticate
|
||||
|
||||
# Verify connection
|
||||
tailscale status
|
||||
```
|
||||
|
||||
### 3. Configure SSH via Tailscale
|
||||
|
||||
Tailscale provides two SSH options:
|
||||
|
||||
#### Option A: Tailscale SSH (Built-in)
|
||||
|
||||
**Enable on each machine**:
|
||||
```bash
|
||||
sudo tailscale up --ssh
|
||||
```
|
||||
|
||||
**Use**:
|
||||
```bash
|
||||
tailscale ssh user@machine-name
|
||||
```
|
||||
|
||||
**Advantages**:
|
||||
- No SSH server configuration needed
|
||||
- Uses Tailscale authentication
|
||||
- Automatic key management
|
||||
|
||||
#### Option B: Standard SSH over Tailscale (Recommended for sshsync)
|
||||
|
||||
**Configure SSH config** to use Tailscale hostnames:
|
||||
|
||||
```bash
|
||||
# ~/.ssh/config
|
||||
|
||||
Host homelab-1
|
||||
HostName homelab-1.tailnet-name.ts.net
|
||||
User admin
|
||||
IdentityFile ~/.ssh/id_ed25519
|
||||
|
||||
# Or use Tailscale IP directly
|
||||
Host homelab-2
|
||||
HostName 100.64.1.10
|
||||
User admin
|
||||
IdentityFile ~/.ssh/id_ed25519
|
||||
```
|
||||
|
||||
**Advantages**:
|
||||
- Works with all SSH tools (including sshsync)
|
||||
- Standard SSH key authentication
|
||||
- More flexibility
|
||||
|
||||
## Getting Tailscale Hostnames and IPs
|
||||
|
||||
### View All Machines
|
||||
|
||||
```bash
|
||||
tailscale status
|
||||
```
|
||||
|
||||
**Output**:
|
||||
```
|
||||
100.64.1.10 homelab-1 user@ linux -
|
||||
100.64.1.11 homelab-2 user@ linux -
|
||||
100.64.1.20 laptop user@ macOS -
|
||||
100.64.1.30 phone user@ iOS offline
|
||||
```
|
||||
|
||||
### Get MagicDNS Hostname
|
||||
|
||||
**Format**: `machine-name.tailnet-name.ts.net`
|
||||
|
||||
**Find your tailnet name**:
|
||||
```bash
|
||||
tailscale status --json | grep -i tailnet
|
||||
```
|
||||
|
||||
Or check in Tailscale admin console: https://login.tailscale.com/admin/machines
|
||||
|
||||
### Get Tailscale IP
|
||||
|
||||
```bash
|
||||
# Your own IP
|
||||
tailscale ip -4
|
||||
|
||||
# Another machine's IP (from status output)
|
||||
tailscale status | grep machine-name
|
||||
```
|
||||
|
||||
## Testing Connectivity
|
||||
|
||||
### Ping via Tailscale
|
||||
|
||||
```bash
|
||||
# Ping by hostname
|
||||
tailscale ping homelab-1
|
||||
|
||||
# Ping by IP
|
||||
tailscale ping 100.64.1.10
|
||||
```
|
||||
|
||||
**Successful output**:
|
||||
```
|
||||
pong from homelab-1 (100.64.1.10) via DERP(nyc) in 45ms
|
||||
pong from homelab-1 (100.64.1.10) via DERP(nyc) in 43ms
|
||||
```
|
||||
|
||||
**Failed output**:
|
||||
```
|
||||
timeout waiting for pong
|
||||
```
|
||||
|
||||
### SSH Test
|
||||
|
||||
```bash
|
||||
# Test SSH connection
|
||||
ssh user@homelab-1.tailnet.ts.net
|
||||
|
||||
# Or with IP
|
||||
ssh user@100.64.1.10
|
||||
```
|
||||
|
||||
## Configuring sshsync with Tailscale
|
||||
|
||||
### Step 1: Add Tailscale Hosts to SSH Config
|
||||
|
||||
```bash
|
||||
vim ~/.ssh/config
|
||||
```
|
||||
|
||||
**Example configuration**:
|
||||
```
|
||||
# Production servers
|
||||
Host prod-web-01
|
||||
HostName prod-web-01.tailnet.ts.net
|
||||
User deploy
|
||||
IdentityFile ~/.ssh/id_ed25519
|
||||
|
||||
Host prod-web-02
|
||||
HostName prod-web-02.tailnet.ts.net
|
||||
User deploy
|
||||
IdentityFile ~/.ssh/id_ed25519
|
||||
|
||||
Host prod-db-01
|
||||
HostName prod-db-01.tailnet.ts.net
|
||||
User deploy
|
||||
IdentityFile ~/.ssh/id_ed25519
|
||||
|
||||
# Homelab
|
||||
Host homelab-1
|
||||
HostName 100.64.1.10
|
||||
User admin
|
||||
IdentityFile ~/.ssh/id_ed25519
|
||||
|
||||
Host homelab-2
|
||||
HostName 100.64.1.11
|
||||
User admin
|
||||
IdentityFile ~/.ssh/id_ed25519
|
||||
|
||||
# Development
|
||||
Host dev-laptop
|
||||
HostName dev-laptop.tailnet.ts.net
|
||||
User developer
|
||||
IdentityFile ~/.ssh/id_ed25519
|
||||
```
|
||||
|
||||
### Step 2: Test Each Host
|
||||
|
||||
```bash
|
||||
# Test connectivity to each host
|
||||
ssh prod-web-01 "hostname"
|
||||
ssh homelab-1 "hostname"
|
||||
ssh dev-laptop "hostname"
|
||||
```
|
||||
|
||||
### Step 3: Initialize sshsync
|
||||
|
||||
```bash
|
||||
# Sync hosts and create groups
|
||||
sshsync sync
|
||||
|
||||
# Add hosts to groups
|
||||
sshsync gadd production
|
||||
# Select: prod-web-01, prod-web-02, prod-db-01
|
||||
|
||||
sshsync gadd homelab
|
||||
# Select: homelab-1, homelab-2
|
||||
|
||||
sshsync gadd development
|
||||
# Select: dev-laptop
|
||||
```
|
||||
|
||||
### Step 4: Verify Configuration
|
||||
|
||||
```bash
|
||||
# List all hosts with status
|
||||
sshsync ls --with-status
|
||||
|
||||
# Test command execution
|
||||
sshsync all "uptime"
|
||||
|
||||
# Test group execution
|
||||
sshsync group production "df -h"
|
||||
```
|
||||
|
||||
## Advanced Tailscale Features
|
||||
|
||||
### Tailnet Lock
|
||||
|
||||
Prevents unauthorized device additions:
|
||||
|
||||
```bash
|
||||
tailscale lock status
|
||||
```
|
||||
|
||||
### Exit Nodes
|
||||
|
||||
Route all traffic through a specific machine:
|
||||
|
||||
```bash
|
||||
# Enable exit node on a machine
|
||||
sudo tailscale up --advertise-exit-node
|
||||
|
||||
# Use exit node from another machine
|
||||
sudo tailscale set --exit-node=exit-node-name
|
||||
```
|
||||
|
||||
### Subnet Routing
|
||||
|
||||
Access networks behind Tailscale machines:
|
||||
|
||||
```bash
|
||||
# Advertise subnet routes
|
||||
sudo tailscale up --advertise-routes=192.168.1.0/24
|
||||
```
|
||||
|
||||
### ACLs (Access Control Lists)
|
||||
|
||||
Control who can access what: https://login.tailscale.com/admin/acls
|
||||
|
||||
**Example ACL**:
|
||||
```json
|
||||
{
|
||||
"acls": [
|
||||
{
|
||||
"action": "accept",
|
||||
"src": ["group:admins"],
|
||||
"dst": ["*:22", "*:80", "*:443"]
|
||||
},
|
||||
{
|
||||
"action": "accept",
|
||||
"src": ["group:developers"],
|
||||
"dst": ["tag:development:*"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Machine Shows Offline
|
||||
|
||||
**Check Tailscale status**:
|
||||
```bash
|
||||
tailscale status
|
||||
```
|
||||
|
||||
**Restart Tailscale**:
|
||||
```bash
|
||||
# macOS
|
||||
brew services restart tailscale
|
||||
|
||||
# Linux
|
||||
sudo systemctl restart tailscaled
|
||||
```
|
||||
|
||||
**Re-authenticate**:
|
||||
```bash
|
||||
sudo tailscale up
|
||||
```
|
||||
|
||||
### Cannot Connect via SSH
|
||||
|
||||
1. **Verify Tailscale connectivity**:
|
||||
```bash
|
||||
tailscale ping machine-name
|
||||
```
|
||||
|
||||
2. **Check SSH is running** on remote:
|
||||
```bash
|
||||
tailscale ssh machine-name "systemctl status sshd"
|
||||
```
|
||||
|
||||
3. **Verify SSH keys**:
|
||||
```bash
|
||||
ssh-add -l
|
||||
```
|
||||
|
||||
4. **Test SSH directly**:
|
||||
```bash
|
||||
ssh -v user@machine-name.tailnet.ts.net
|
||||
```
|
||||
|
||||
### High Latency
|
||||
|
||||
**Check connection method**:
|
||||
```bash
|
||||
tailscale status
|
||||
```
|
||||
|
||||
Look for "direct" vs "DERP relay":
|
||||
- **Direct**: Low latency (< 50ms)
|
||||
- **DERP relay**: Higher latency (100-200ms)
|
||||
|
||||
**Force direct connection**:
|
||||
```bash
|
||||
# Ensure both machines can establish P2P
|
||||
# May require NAT traversal
|
||||
```
|
||||
|
||||
### MagicDNS Not Working
|
||||
|
||||
**Enable MagicDNS**:
|
||||
1. Go to https://login.tailscale.com/admin/dns
|
||||
2. Enable MagicDNS
|
||||
|
||||
**Verify**:
|
||||
```bash
|
||||
nslookup machine-name.tailnet.ts.net
|
||||
```
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
1. **Use SSH keys**, not passwords
|
||||
2. **Enable Tailnet Lock** to prevent unauthorized devices
|
||||
3. **Use ACLs** to restrict access
|
||||
4. **Regularly review** connected devices
|
||||
5. **Set up key expiry** for team members who leave
|
||||
6. **Use tags** for machine roles
|
||||
7. **Enable two-factor auth** for Tailscale account
|
||||
|
||||
## Monitoring
|
||||
|
||||
### Check Network Status
|
||||
|
||||
```bash
|
||||
# All machines
|
||||
tailscale status
|
||||
|
||||
# Self status
|
||||
tailscale status --self
|
||||
|
||||
# JSON format for parsing
|
||||
tailscale status --json
|
||||
```
|
||||
|
||||
### View Logs
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
tail -f /var/log/tailscaled.log
|
||||
|
||||
# Linux
|
||||
journalctl -u tailscaled -f
|
||||
```
|
||||
|
||||
## Use Cases with sshsync
|
||||
|
||||
### 1. Deploy to All Production Servers
|
||||
|
||||
```bash
|
||||
sshsync push --group production --recurse ./dist /var/www/app
|
||||
sshsync group production "cd /var/www/app && pm2 restart all"
|
||||
```
|
||||
|
||||
### 2. Collect Logs from All Servers
|
||||
|
||||
```bash
|
||||
sshsync pull --group production /var/log/app/error.log ./logs/
|
||||
```
|
||||
|
||||
### 3. Update All Homelab Machines
|
||||
|
||||
```bash
|
||||
sshsync group homelab "sudo apt update && sudo apt upgrade -y"
|
||||
```
|
||||
|
||||
### 4. Check Disk Space Everywhere
|
||||
|
||||
```bash
|
||||
sshsync all "df -h /"
|
||||
```
|
||||
|
||||
### 5. Sync Configuration Across Machines
|
||||
|
||||
```bash
|
||||
sshsync push --all ~/dotfiles/.bashrc ~/.bashrc
|
||||
sshsync push --all ~/dotfiles/.vimrc ~/.vimrc
|
||||
```
|
||||
|
||||
## Summary
|
||||
|
||||
Tailscale + sshsync = **Powerful Remote Management**
|
||||
|
||||
- ✅ Secure connections everywhere (WireGuard encryption)
|
||||
- ✅ No firewall configuration needed
|
||||
- ✅ Easy addressing (MagicDNS)
|
||||
- ✅ Multi-host operations (sshsync groups)
|
||||
- ✅ Works from anywhere
|
||||
|
||||
**Quick Start**:
|
||||
1. Install Tailscale: `brew install tailscale`
|
||||
2. Connect: `sudo tailscale up`
|
||||
3. Configure SSH config with Tailscale hostnames
|
||||
4. Initialize sshsync: `sshsync sync`
|
||||
5. Start managing: `sshsync all "uptime"`
|
||||
|
||||
For more: https://tailscale.com/kb/
|
||||
Reference in New Issue
Block a user