zhongwei/gh-human-frontier-labs-inc-human-frontier-labs-marketplace-plugins-tailscale-sshsync-agent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
14c678ceac362b99ae37a448a6859dfa1227898b
gh-human-frontier-labs-inc-…/references/tailscale-integration.md
Zhongwei Li 14c678ceac Initial commit
2025-11-29 18:47:40 +08:00

8.2 KiB
Raw Blame History

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:

brew install tailscale

Linux:

curl -fsSL https://tailscale.com/install.sh | sh

Verify Installation:

tailscale version

2. Connect to Tailscale

# 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:

sudo tailscale up --ssh

Use:

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:

# ~/.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

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:

tailscale status --json | grep -i tailnet

Or check in Tailscale admin console: https://login.tailscale.com/admin/machines

Get Tailscale IP

# Your own IP
tailscale ip -4

# Another machine's IP (from status output)
tailscale status | grep machine-name

Testing Connectivity

Ping via Tailscale

# 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

# 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

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

# Test connectivity to each host
ssh prod-web-01 "hostname"
ssh homelab-1 "hostname"
ssh dev-laptop "hostname"

Step 3: Initialize sshsync

# 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

# 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:

tailscale lock status

Exit Nodes

Route all traffic through a specific machine:

# 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:

# 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:

{
  "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:

tailscale status

Restart Tailscale:

# macOS
brew services restart tailscale

# Linux
sudo systemctl restart tailscaled

Re-authenticate:

sudo tailscale up

Cannot Connect via SSH

  1. Verify Tailscale connectivity:

    tailscale ping machine-name

  2. Check SSH is running on remote:

    tailscale ssh machine-name "systemctl status sshd"

  3. Verify SSH keys:

    ssh-add -l

  4. Test SSH directly:

    ssh -v user@machine-name.tailnet.ts.net

High Latency

Check connection method:

tailscale status

Look for "direct" vs "DERP relay":

  • Direct: Low latency (< 50ms)
  • DERP relay: Higher latency (100-200ms)

Force direct connection:

# 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:

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

# All machines
tailscale status

# Self status
tailscale status --self

# JSON format for parsing
tailscale status --json

View Logs

# macOS
tail -f /var/log/tailscaled.log

# Linux
journalctl -u tailscaled -f

Use Cases with sshsync

1. Deploy to All Production Servers

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

sshsync pull --group production /var/log/app/error.log ./logs/

3. Update All Homelab Machines

sshsync group homelab "sudo apt update && sudo apt upgrade -y"

4. Check Disk Space Everywhere

sshsync all "df -h /"

5. Sync Configuration Across Machines

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 View Git Blame Copy Permalink