From d34cea9df638b4f51a7ef657fbac7c2b8831869b Mon Sep 17 00:00:00 2001 From: Kaloyan Danchev Date: Sat, 31 Jan 2026 18:43:27 +0200 Subject: [PATCH] Add MikroTik Tailscale container documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- docs/18-MIKROTIK-TAILSCALE.md | 224 ++++++++++++++++++++++++++++++++++ 1 file changed, 224 insertions(+) create mode 100644 docs/18-MIKROTIK-TAILSCALE.md diff --git a/docs/18-MIKROTIK-TAILSCALE.md b/docs/18-MIKROTIK-TAILSCALE.md new file mode 100644 index 0000000..15c1c1e --- /dev/null +++ b/docs/18-MIKROTIK-TAILSCALE.md @@ -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= +``` + +### 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