ec9659d0cb
All checks were successful
ci/woodpecker/push/woodpecker Pipeline was successful
Major documentation cleanup after VLAN migration completion: - Archive 12 VLAN project docs to archive/vlan-migration/ - Archive 5 done WIP docs (VLAN proposals, AI stack, Fossorial, DNS backup) - Create standing reference docs 08-DNS-ARCHITECTURE and 09-TAILSCALE-VPN - Renumber docs to clean 01-09 sequence with merged CHANGELOG - Update all active docs from stale 192.168.31.x to current VLAN 10 IPs - Fix CSS1 (.10.9→.10.3) and ZX1 (.10.7→.10.4) IPs in hardware inventory - Clean 06-VLAN-DEVICE-ASSIGNMENT: remove migration columns/sections, fix VLAN 25 subnet Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
209 lines
7.1 KiB
Markdown
209 lines
7.1 KiB
Markdown
# MikroTik Tailscale Container Setup
|
|
|
|
**Last Updated:** 2026-02-06
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
Tailscale VPN running as a container on MikroTik hAP ax³, providing remote access to the home network via the Tailscale mesh network.
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ MikroTik hAP ax³ (192.168.10.1) │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────┐ │
|
|
│ │ Container Network (172.17.0.0/24) │ │
|
|
│ │ │ │
|
|
│ │ ┌─────────────────────┐ ┌─────────────────────────┐ │ │
|
|
│ │ │ AdGuard Home │ │ Tailscale │ │ │
|
|
│ │ │ 172.17.0.2 │ │ 172.17.0.3 │ │ │
|
|
│ │ │ veth-adguard │ │ veth-tailscale │ │ │
|
|
│ │ └─────────────────────┘ └─────────────────────────┘ │ │
|
|
│ │ │ │ │ │
|
|
│ │ └───────────┬───────────────┘ │ │
|
|
│ │ │ │ │
|
|
│ │ Gateway: 172.17.0.1 │ │
|
|
│ └─────────────────────────────────────────────────────────────┘ │
|
|
│ │ │
|
|
│ NAT Masquerade │
|
|
│ │ │
|
|
│ WAN (ether1) │
|
|
└──────────────────────────────┬──────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────┐
|
|
│ Tailscale Network │
|
|
│ 100.x.x.x mesh │
|
|
│ │
|
|
│ Home Router IP: │
|
|
│ 100.74.219.35 │
|
|
└─────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## Container Details
|
|
|
|
| Setting | Value |
|
|
|---------|-------|
|
|
| Image | tailscale/tailscale:latest |
|
|
| Interface | veth-tailscale |
|
|
| Container IP | 172.17.0.3/24 |
|
|
| Gateway | 172.17.0.1 |
|
|
| Tailscale IP | 100.74.219.35 |
|
|
| Root dir | usb1/tailscale/root |
|
|
| State mount | usb1/tailscale → /var/lib/tailscale |
|
|
| DNS | 8.8.8.8 |
|
|
| Start on boot | Yes |
|
|
| Networking mode | Userspace (TS_USERSPACE=true) |
|
|
|
|
---
|
|
|
|
## Environment Variables
|
|
|
|
| Variable | Value | Purpose |
|
|
|----------|-------|---------|
|
|
| TS_AUTHKEY | tskey-auth-... | One-time auth key (used during setup) |
|
|
| TS_STATE_DIR | /var/lib/tailscale | Persistent state directory |
|
|
| TS_USERSPACE | true | Required for MikroTik containers (no /dev/net/tun) |
|
|
|
|
---
|
|
|
|
## Network Configuration
|
|
|
|
### veth Interface
|
|
|
|
```routeros
|
|
/interface veth add address=172.17.0.3/24 gateway=172.17.0.1 name=veth-tailscale
|
|
```
|
|
|
|
### Gateway IP on Interface
|
|
|
|
```routeros
|
|
/ip address add address=172.17.0.1/24 interface=veth-tailscale comment="Tailscale container gateway"
|
|
```
|
|
|
|
### NAT Masquerade for Internet Access
|
|
|
|
```routeros
|
|
/ip firewall nat add chain=srcnat action=masquerade src-address=172.17.0.0/24 out-interface-list=WAN comment="Container network NAT"
|
|
```
|
|
|
|
### Firewall Forward Rules
|
|
|
|
```routeros
|
|
/ip firewall filter add chain=forward action=accept dst-address=172.17.0.0/24 comment="[Container] Forward to container network"
|
|
/ip firewall filter add chain=forward action=accept src-address=172.17.0.0/24 comment="[Container] Forward from container network"
|
|
```
|
|
|
|
---
|
|
|
|
## Container Setup Commands
|
|
|
|
### Create Mounts
|
|
|
|
```routeros
|
|
/container mounts add list=ts-state src=usb1/tailscale dst=/var/lib/tailscale
|
|
```
|
|
|
|
### Create Environment Variables
|
|
|
|
```routeros
|
|
/container envs add list=ts-env key=TS_STATE_DIR value=/var/lib/tailscale
|
|
/container envs add list=ts-env key=TS_USERSPACE value=true
|
|
/container envs add list=ts-env key=TS_AUTHKEY value=<your-auth-key>
|
|
```
|
|
|
|
### Create Container
|
|
|
|
```routeros
|
|
/container add remote-image=tailscale/tailscale:latest interface=veth-tailscale \
|
|
root-dir=usb1/tailscale/root mountlists=ts-state envlists=ts-env \
|
|
dns=8.8.8.8 start-on-boot=yes logging=yes
|
|
```
|
|
|
|
---
|
|
|
|
## Management
|
|
|
|
### Check Container Status
|
|
|
|
```routeros
|
|
/container print
|
|
```
|
|
|
|
### View Logs
|
|
|
|
```routeros
|
|
/log print where topics~"container" and message~"tailscale"
|
|
```
|
|
|
|
### Start/Stop Container
|
|
|
|
```routeros
|
|
/container start [find name~"tailscale"]
|
|
/container stop [find name~"tailscale"]
|
|
```
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Container Won't Start (Exit Status 1)
|
|
|
|
**Cause:** Missing /dev/net/tun device (default for Tailscale)
|
|
|
|
**Solution:** Enable userspace networking mode:
|
|
```routeros
|
|
/container envs add list=ts-env key=TS_USERSPACE value=true
|
|
```
|
|
|
|
### Can't Reach Internet from Container
|
|
|
|
**Cause:** Missing NAT masquerade or gateway IP
|
|
|
|
**Solution:**
|
|
1. Verify gateway IP on veth interface:
|
|
```routeros
|
|
/ip address print where interface=veth-tailscale
|
|
```
|
|
|
|
2. Verify NAT masquerade rule:
|
|
```routeros
|
|
/ip firewall nat print where src-address=172.17.0.0/24
|
|
```
|
|
|
|
### Container Not Connecting to Tailscale
|
|
|
|
1. Check DNS resolution works (logs should show no timeout)
|
|
2. Verify auth key is valid and not expired
|
|
3. Check firewall isn't blocking outbound HTTPS
|
|
|
|
---
|
|
|
|
## Tailscale Network Devices
|
|
|
|
| Tailscale IP | Device | Status |
|
|
|--------------|--------|--------|
|
|
| 100.74.219.35 | MikroTik hAP ax³ (container) | Online |
|
|
| 100.100.208.70 | xtrm-unraid | Online |
|
|
| 100.112.103.7 | hapax3 (old native install) | Offline |
|
|
| 100.75.93.123 | mikrotik-tailscale (previous container) | Offline |
|
|
|
|
---
|
|
|
|
## Important Notes
|
|
|
|
1. **Userspace Networking Required:** MikroTik containers don't have /dev/net/tun access, so TS_USERSPACE=true is mandatory
|
|
|
|
2. **Auth Key:** After initial authentication, the key is no longer needed - state is persisted in the mount
|
|
|
|
3. **Container Network:** Both AdGuard and Tailscale share the 172.17.0.0/24 network but have separate veth interfaces
|
|
|
|
4. **Accept Routes:** If subnet routing is needed, add TS_EXTRA_ARGS="--accept-routes" to environment
|