# Tailscale VPN Setup Guide

Tailscale provides secure mesh networking across all your machines with zero-config VPN connectivity.

## Prerequisites
- Tailscale account (free at https://tailscale.com)
- Auth key from Tailscale admin console

## Quick Setup (3 Steps)

### 1. Get Your Auth Key
1. Visit https://login.tailscale.com/admin/settings/keys
2. Click "Generate auth key"
3. Configure key:
   - **Reusable**: Yes (for multiple machines)
   - **Expiration**: 90 days or longer
4. Copy the key (starts with `tskey-auth-`)

### 2. Store Key Securely
```bash
make create-vault
```
Add this content when prompted:
```yaml
---
vault_tailscale_auth_key: "tskey-auth-your-actual-key-here"
```

### 3. Deploy Tailscale
```bash
# Preview changes (dry run)
make tailscale-check

# Install on all machines
make tailscale

# Check status
make tailscale-status
```

## Deployment Options

### Target Specific Machines
```bash
# Development machines only
make tailscale-dev

# Specific hosts
ansible-playbook playbooks/tailscale.yml --limit "dev01,bottom"
```

### Manual Installation
```bash
# With custom auth key (not recommended - use vault instead)
ansible-playbook playbooks/tailscale.yml -e "tailscale_auth_key=your-key"

# As part of existing playbooks
ansible-playbook playbooks/development.yml --tags tailscale
```

## Configuration

### Global Settings (`inventories/production/group_vars/all/main.yml`)
```yaml
tailscale_auth_key: "{{ vault_tailscale_auth_key }}"  # From vault
tailscale_accept_routes: true                         # Accept subnet routes
tailscale_accept_dns: true                           # Accept DNS settings
tailscale_ssh: true                                  # Enable SSH over Tailscale
```

### Host-Specific Settings (`inventories/production/host_vars/<hostname>.yml`)
```yaml
tailscale_hostname: "custom-name"              # Override hostname
tailscale_advertise_routes: "192.168.1.0/24"  # Share local subnet
tailscale_shields_up: false                   # Block incoming connections
```

## Troubleshooting

### Check Service Status
```bash
# Via Ansible
make tailscale-status

# On target machine
sudo systemctl status tailscaled
tailscale status
```

### View Logs
```bash
sudo journalctl -u tailscaled -f
```

### Manual Connection
If auth key wasn't provided during setup:
```bash
sudo tailscale up
```

### Reset Connection
```bash
ansible-playbook playbooks/tailscale.yml -e "tailscale_reset=true"
```

## Security Best Practices
- Always use Ansible Vault for auth keys
- Consider ephemeral keys for one-time setups
- Authorize machines in Tailscale admin console
- Review SSH settings if enabling Tailscale SSH

## Supported Platforms
- **Ubuntu**: focal, jammy, noble
- **Debian**: bullseye, bookworm, trixie
- **Alpine Linux**: all versions

The role automatically detects OS and uses appropriate package manager.

## How It Works

1. **Playbook runs** → looks for `tailscale_auth_key`
2. **Checks inventory group vars** → finds `{{ vault_tailscale_auth_key }}`
3. **Decrypts vault** → retrieves actual auth key
4. **Installs Tailscale** → configures with your settings
5. **Connects to network** → machine appears in admin console

## Related Documentation
- [Ansible Vault Guide](./vault.md) - Managing secrets securely
- [Network Architecture](../reference/network.md) - Overall network design