Add MikroTik Tailscale container documentation
All checks were successful
ci/woodpecker/push/woodpecker Pipeline was successful
All checks were successful
ci/woodpecker/push/woodpecker Pipeline was successful
Documents the Tailscale container setup on MikroTik hAP ax³: - Userspace networking mode (TS_USERSPACE=true) required for RouterOS containers - Container network configuration (172.17.0.0/24) - NAT masquerade for internet access - Environment variables and mount configuration - Troubleshooting guide for common issues Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Kaloyan Danchev
224
docs/18-MIKROTIK-TAILSCALE.md
Normal file
224
docs/18-MIKROTIK-TAILSCALE.md
Normal file
@@ -0,0 +1,224 @@
|
||||
# MikroTik Tailscale Container Setup
|
||||
|
||||
**Created:** 2026-01-31
|
||||
**Status:** Implemented
|
||||
**Backup:** `tailscale-working-2026-01-31.backup`
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
---
|
||||
|
||||
## Backups
|
||||
|
||||
| Backup | Description |
|
||||
|--------|-------------|
|
||||
| pre-tailscale-2026-01-31 | Before Tailscale setup |
|
||||
| tailscale-working-2026-01-31 | Tailscale container running |
|
||||
|
||||
---
|
||||
|
||||
**Document Version:** 1.0
|
||||
**Last Updated:** 2026-01-31
|
||||
Reference in New Issue
Block a user