129 lines
3.2 KiB
Markdown
129 lines
3.2 KiB
Markdown
# 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 tailscale-playbook.yml --limit "dev01,bottom"
|
|
```
|
|
|
|
### Manual Installation
|
|
```bash
|
|
# With custom auth key (not recommended - use vault instead)
|
|
ansible-playbook tailscale-playbook.yml -e "tailscale_auth_key=your-key"
|
|
|
|
# As part of existing playbooks
|
|
ansible-playbook dev-playbook.yml --tags tailscale
|
|
```
|
|
|
|
## Configuration
|
|
|
|
### Global Settings (`group_vars/all.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 (`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 tailscale-playbook.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 `all.yml`** → 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 |