infrastructure/docs/09-TAILSCALE-VPN.md

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

/interface veth add address=172.17.0.3/24 gateway=172.17.0.1 name=veth-tailscale

Gateway IP on Interface

/ip address add address=172.17.0.1/24 interface=veth-tailscale comment="Tailscale container gateway"

NAT Masquerade for Internet Access

/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

/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

/container mounts add list=ts-state src=usb1/tailscale dst=/var/lib/tailscale

Create Environment Variables

/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

/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

/container print

View Logs

/log print where topics~"container" and message~"tailscale"

Start/Stop Container

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

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

/ip address print where interface=veth-tailscale

2. Verify NAT masquerade rule:

/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