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>
7.4 KiB
7.4 KiB
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
/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:
- Verify gateway IP on veth interface:
/ip address print where interface=veth-tailscale
- Verify NAT masquerade rule:
/ip firewall nat print where src-address=172.17.0.0/24
Container Not Connecting to Tailscale
- Check DNS resolution works (logs should show no timeout)
- Verify auth key is valid and not expired
- 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
-
Userspace Networking Required: MikroTik containers don't have /dev/net/tun access, so TS_USERSPACE=true is mandatory
-
Auth Key: After initial authentication, the key is no longer needed - state is persisted in the mount
-
Container Network: Both AdGuard and Tailscale share the 172.17.0.0/24 network but have separate veth interfaces
-
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