Compare commits
171
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
ca2c76e77e | ||
|
|
787cbb0c10 | ||
|
|
14d77c183d | ||
|
|
e763cfeda4 | ||
|
|
06a2bd64b9 | ||
|
|
a280b5d517 | ||
|
|
c5049a1bf5 | ||
|
|
c0ffa09887 | ||
|
|
9e02e86f4f | ||
|
|
ab4523a6c3 | ||
|
|
45868e68ab | ||
|
|
8aec78b500 | ||
|
|
b63aadbc79 | ||
|
|
ce8b20c4a5 | ||
|
|
7c8a03dfff | ||
|
|
1eb7c57129 | ||
|
|
40979fdd4c | ||
|
|
f9d8ee2b36 | ||
|
|
c21d66f105 | ||
|
|
c71905192d | ||
|
|
b1bf9719c0
|
||
|
|
b931314a4c | ||
|
|
86670c94bb | ||
|
|
c05cbc1401 | ||
|
|
b4a1cc860f | ||
|
|
3ac116aab5 | ||
|
|
b2f2443421 | ||
|
|
80edf9679f | ||
|
|
08bb3e38dd | ||
|
|
c6ed7992d6 | ||
|
|
74d24e7bc8 | ||
|
|
8bd883a29e | ||
|
|
42e01d5510 | ||
|
|
c84a0bff3d | ||
|
|
0394699170 | ||
|
|
43890cbc7d | ||
|
|
494230875a | ||
|
|
b8fb844468 | ||
|
|
e428d79ed7 | ||
|
|
ac132d5701 | ||
|
|
5f5c9c58a8 | ||
|
|
b556029a10 | ||
|
|
2d731f7853 | ||
|
|
1136539f49 | ||
|
|
a3ed139d44 | ||
|
|
101a64d779 | ||
|
|
ecf8f35c89 | ||
|
|
4ace464a2b | ||
|
|
e29e6f204b | ||
|
|
d7635a7da9 | ||
|
|
b7228d98d2 | ||
|
|
9734687641 | ||
|
|
97d7567266 | ||
|
|
149a3beb06 | ||
|
|
af00049b21 | ||
|
|
cbf8599a7f | ||
|
|
458cc25c05 | ||
|
|
84379aebf1 | ||
|
|
82f239be1f | ||
|
|
41012011d9 | ||
|
|
63d16c7ee3 | ||
|
|
6323311920 | ||
|
|
b5c9bd8182 | ||
|
|
1e55402ce1 | ||
|
|
3f2d48f321 | ||
|
|
c5e1c8be24 | ||
|
|
db9361045d | ||
|
|
561f067bb6 | ||
|
|
284ea0ddad | ||
|
|
a2a2c4bdc8 | ||
|
|
5d6fce8985 | ||
|
|
9ef4a1b006 | ||
|
|
40be2b1ab6 | ||
|
|
b32a1d495e | ||
|
|
22b57a8ce0 | ||
|
|
0f6860c0ed | ||
|
|
fabcc8f43d | ||
|
|
7a32c26fbc | ||
|
|
290c8e71ca | ||
|
|
fe979a6698 | ||
|
|
aec542e727 | ||
|
|
62a9f41071 | ||
|
|
0e42ef9a25 | ||
|
|
fb2eda403b | ||
|
|
391fabddf9 | ||
|
|
38ddb5fc06 | ||
|
|
cc6fbedf5b | ||
|
|
ff97e5e630 | ||
|
|
b5da91e772 | ||
|
|
8363cfe970 | ||
|
|
0fa1df814f | ||
|
|
77d7cdcd25 | ||
|
|
a121513f32 | ||
|
|
a396d20a18 | ||
|
|
0753c314a9
|
||
|
|
cd83a6146f | ||
|
|
b96f88680f | ||
|
|
8092d27cb9 | ||
|
|
5bb34731cb | ||
|
|
c191d8dc47 | ||
|
|
ad3850b634 | ||
|
|
0d8851a16a | ||
|
|
9fc48bac7b | ||
|
|
2e2ccb4f3e | ||
|
|
e009040cb4
|
||
|
|
492230a746 | ||
|
|
0a8a40fdb8
|
||
|
|
7482ddb832
|
||
|
|
da2b3b5d3a | ||
|
|
d03c7d3da7
|
||
|
|
85f522bce1 | ||
|
|
509762c1b4 | ||
|
|
06083dcf58 | ||
|
|
ff60452758
|
||
|
|
524b83d911
|
||
|
|
8fee49bf09
|
||
|
|
b8dd344a93 | ||
|
|
3ff4666495
|
||
|
|
43f913cffc | ||
|
|
43698b733d | ||
|
|
ee5ca68fc3
|
||
|
|
8a550f23d8
|
||
|
|
a34f30483b | ||
|
|
26debfaf30 | ||
|
|
cae5aca3b3 | ||
|
|
16fd2170db | ||
|
|
b7f3bdbbc6 | ||
|
|
c2fee4d239 | ||
|
|
cb70afb345
|
||
|
|
568f114c6e | ||
|
|
6ba07dd23b
|
||
|
|
3ae0ab3075 | ||
|
|
ebf011908a
|
||
|
|
6c166066a6 | ||
|
|
75b95fe4c4 | ||
|
|
c8b5101416 | ||
|
|
11d12737f7 | ||
|
|
cba8447fa7 | ||
|
|
6b69bd7492 | ||
|
|
d085d3120e | ||
|
|
f576dc6f1f | ||
|
|
e7dcdba8aa | ||
|
|
bd6c6cf4b2 | ||
|
|
1a8b065283
|
||
|
|
7dacdccc01 | ||
|
|
8a34988dd4
|
||
|
|
6e5004aa0e | ||
|
|
57df037137 | ||
|
|
315fd630e3
|
||
|
|
1bc10bcb6e
|
||
|
|
745075f38c | ||
|
|
9ff1623958 | ||
|
|
94427bd3f4 | ||
|
|
37938ac471 | ||
|
|
2ce364ea15 | ||
|
|
3057685588 | ||
|
|
3cf6a1faab
|
||
|
|
43ed7efe98 | ||
|
|
d45799a314 | ||
|
|
a1da2564fd | ||
|
|
9788fe146b | ||
|
|
f69263c480 | ||
|
|
ae8c114109
|
||
|
|
ea0d90d8f0
|
||
|
|
7d1b9f99a5
|
||
|
|
7a6efb52ec
|
||
|
|
e0cbaee48b
|
||
|
|
01057e78b8
|
||
|
|
f7ddd164b3
|
||
|
|
082703a6b8
|
||
|
|
864859a5a0
|
No files matched your search
@@ -0,0 +1,39 @@
|
||||
# Build validation for pull requests (and pushes to main).
|
||||
#
|
||||
# Builds the full multi-arch image but does NOT push it anywhere — it only
|
||||
# proves the Dockerfile still builds for every supported architecture. This is
|
||||
# the gate Renovate automerge waits on: a dependency bump that breaks the build
|
||||
# fails this check and will NOT be automerged (and therefore never reaches
|
||||
# :stable or the routers).
|
||||
#
|
||||
# Reports pass/fail status back to Gitea, so it shows up as a required check on
|
||||
# the PR.
|
||||
|
||||
# Changes that can't affect the image don't trigger the build: docs and the
|
||||
# RouterOS-side script (routeros/**: lives on the router, not in the image).
|
||||
# NOTE: if Gitea is ever configured to REQUIRE this check for merging, a
|
||||
# PR touching only excluded files will have no check at all — exempt such PRs
|
||||
# or merge manually. Renovate PRs always touch the Dockerfile or pipeline
|
||||
# files, so the automerge gate is unaffected by these exclusions.
|
||||
when:
|
||||
- event: pull_request
|
||||
path:
|
||||
exclude: &non_image_paths
|
||||
- '**/*.md'
|
||||
- 'docs/**'
|
||||
- 'routeros/**'
|
||||
- 'renovate.json'
|
||||
- event: push
|
||||
branch: main
|
||||
path:
|
||||
exclude: *non_image_paths
|
||||
|
||||
steps:
|
||||
- name: Build all arches (no push)
|
||||
image: woodpeckerci/plugin-docker-buildx:6.1.2
|
||||
privileged: true
|
||||
settings:
|
||||
platforms: linux/amd64,linux/arm64,linux/arm/v7
|
||||
dry_run: true
|
||||
build_args:
|
||||
- OCI_VERSION=ci-${CI_COMMIT_SHA}
|
||||
@@ -13,13 +13,23 @@
|
||||
# unchanged, so no tag is created and nothing is released — they ride along
|
||||
# with the next Tailscale bump or manual tag.
|
||||
|
||||
# Skipped for pushes that can't introduce a new Tailscale version:
|
||||
# TAILSCALE_VERSION lives in the Dockerfile, so a push touching only docs or
|
||||
# the RouterOS-side script can never produce a new version to tag (the job
|
||||
# would just no-op after spinning up OpenBao + git containers).
|
||||
when:
|
||||
- event: push
|
||||
branch: main
|
||||
path:
|
||||
exclude:
|
||||
- '**/*.md'
|
||||
- 'docs/**'
|
||||
- 'routeros/**'
|
||||
- 'renovate.json'
|
||||
|
||||
steps:
|
||||
- name: Get git token from OpenBao
|
||||
image: quay.io/openbao/openbao:2.5.4
|
||||
image: quay.io/openbao/openbao:2.7.1
|
||||
environment:
|
||||
VAULT_ADDR: https://openbao.lumpiasty.xyz:8200
|
||||
ROLE_ID:
|
||||
@@ -34,7 +44,7 @@ steps:
|
||||
- bao kv get -mount secret -field RENOVATE_TOKEN renovate > /woodpecker/git_token
|
||||
|
||||
- name: Auto-tag mt.1 on Tailscale bump
|
||||
image: alpine/git:2.49.1
|
||||
image: alpine/git:v2.54.0
|
||||
environment:
|
||||
CI_REPO_URL: https://gitea.lumpiasty.xyz/lumpiasty/mikrotik-tailscale.git
|
||||
commands:
|
||||
@@ -61,3 +71,10 @@ steps:
|
||||
- git tag -a "$TAG" -m "Automated release for Tailscale $TS"
|
||||
- git push "https://woodpecker:$GIT_TOKEN@gitea.lumpiasty.xyz/lumpiasty/mikrotik-tailscale.git" "$TAG"
|
||||
- echo "Pushed $TAG"
|
||||
- name: Invalidate OpenBao token
|
||||
image: quay.io/openbao/openbao:2.7.1
|
||||
environment:
|
||||
VAULT_ADDR: https://openbao.lumpiasty.xyz:8200
|
||||
commands:
|
||||
- export VAULT_TOKEN=$(cat /woodpecker/.vault_id)
|
||||
- bao write -f auth/token/revoke-self
|
||||
@@ -25,7 +25,7 @@ when:
|
||||
|
||||
steps:
|
||||
- name: Get registry creds from OpenBao
|
||||
image: quay.io/openbao/openbao:2.5.4
|
||||
image: quay.io/openbao/openbao:2.7.1
|
||||
environment:
|
||||
VAULT_ADDR: https://openbao.lumpiasty.xyz:8200
|
||||
ROLE_ID:
|
||||
@@ -43,7 +43,7 @@ steps:
|
||||
- 'printf "PLUGIN_PASSWORD=%s\n" "$(bao kv get -mount secret -field REGISTRY_PASSWORD container-registry)" >> /woodpecker/registry.env'
|
||||
|
||||
- name: Build and push multi-arch image
|
||||
image: woodpeckerci/plugin-docker-buildx:5.2.2
|
||||
image: woodpeckerci/plugin-docker-buildx:6.1.2
|
||||
privileged: true
|
||||
settings:
|
||||
registry: gitea.lumpiasty.xyz
|
||||
@@ -56,3 +56,10 @@ steps:
|
||||
- OCI_VERSION=${CI_COMMIT_TAG}
|
||||
# Credentials (PLUGIN_USERNAME / PLUGIN_PASSWORD) come from OpenBao.
|
||||
env_file: /woodpecker/registry.env
|
||||
- name: Invalidate OpenBao token
|
||||
image: quay.io/openbao/openbao:2.7.1
|
||||
environment:
|
||||
VAULT_ADDR: https://openbao.lumpiasty.xyz:8200
|
||||
commands:
|
||||
- export VAULT_TOKEN=$(cat /woodpecker/.vault_id)
|
||||
- bao write -f auth/token/revoke-self
|
||||
@@ -30,7 +30,7 @@ skip_clone: true
|
||||
|
||||
steps:
|
||||
- name: Get renovate token from OpenBao
|
||||
image: quay.io/openbao/openbao:2.5.4
|
||||
image: quay.io/openbao/openbao:2.7.1
|
||||
environment:
|
||||
VAULT_ADDR: https://openbao.lumpiasty.xyz:8200
|
||||
ROLE_ID:
|
||||
@@ -45,8 +45,9 @@ steps:
|
||||
- bao kv get -mount secret -field RENOVATE_TOKEN renovate > /woodpecker/renovate_token
|
||||
- bao kv get -mount secret -field GITHUB_COM_TOKEN renovate > /woodpecker/github_com_token
|
||||
- name: renovate
|
||||
pull: true
|
||||
# Renovate's built-in "woodpecker" manager tracks this image automatically.
|
||||
image: renovate/renovate:43.194.0
|
||||
image: renovate/renovate:44
|
||||
environment:
|
||||
# --- platform / target ---
|
||||
RENOVATE_PLATFORM: gitea
|
||||
@@ -58,8 +59,12 @@ steps:
|
||||
# Use the committed renovate.json; don't open an onboarding PR.
|
||||
RENOVATE_ONBOARDING: "false"
|
||||
RENOVATE_REQUIRE_CONFIG: "optional"
|
||||
# Git identity for the branches/commits Renovate creates.
|
||||
RENOVATE_GIT_AUTHOR: "Renovate Bot <renovate@localhost>"
|
||||
# Git identity for the branches/commits Renovate creates. MUST match the
|
||||
# bot's Gitea account email: platform actions (automerge merge commits,
|
||||
# "update branch") are attributed to the account email, and Renovate
|
||||
# flags branches containing commits from unrecognized emails as
|
||||
# "edited by someone else" and stops rebasing them.
|
||||
RENOVATE_GIT_AUTHOR: "Renovate Bot <renovate@lumpiasty.xyz>"
|
||||
# GitHub token (read-only, no repo access) lets Renovate fetch release
|
||||
# notes / changelogs and avoids GitHub API rate limits for the
|
||||
# github-releases datasource (tailscale). Optional but recommended.
|
||||
@@ -71,7 +76,7 @@ steps:
|
||||
- export GITHUB_COM_TOKEN=$(cat /woodpecker/github_com_token)
|
||||
- /usr/local/sbin/renovate-entrypoint.sh renovate
|
||||
- name: Invalidate OpenBao token
|
||||
image: quay.io/openbao/openbao:2.5.4
|
||||
image: quay.io/openbao/openbao:2.7.1
|
||||
environment:
|
||||
VAULT_ADDR: https://openbao.lumpiasty.xyz:8200
|
||||
commands:
|
||||
|
||||
+289
-47
@@ -1,4 +1,4 @@
|
||||
# syntax=docker/dockerfile:1.24.0@sha256:87999aa3d42bdc6bea60565083ee17e86d1f3339802f543c0d03998580f9cb89
|
||||
# syntax=docker/dockerfile:1.28.0@sha256:bb22d9815c728170f72750f4e5b0d672e06176142e1d602c7e66c050100b7e5b
|
||||
# =============================================================================
|
||||
# Multi-architecture build
|
||||
# =============================================================================
|
||||
@@ -12,17 +12,30 @@
|
||||
# it would need a glibc (Debian) base and produces a much larger image. See
|
||||
# README for details if you need it.
|
||||
#
|
||||
# The Go builder cross-compiles, so it always runs NATIVELY on the build host
|
||||
# ($BUILDPLATFORM) for speed; only the busybox stage and the final image run on
|
||||
# the target platform.
|
||||
# Both the Go (Tailscale) stage and the C (busybox) stage cross-compile: they
|
||||
# always run NATIVELY on the build host ($BUILDPLATFORM) and produce binaries
|
||||
# for $TARGETPLATFORM. This eliminates QEMU emulation entirely from the build,
|
||||
# which is the main source of slowness in multi-arch builds. Only the final
|
||||
# scratch stage pulls in the target-arch-specific layers (CA certs, busybox
|
||||
# rootfs) which are just file copies with no emulated execution.
|
||||
#
|
||||
# Cross-compilation for C (busybox) is provided by tonistiigi/xx, which
|
||||
# configures clang+lld as a cross-compiler and installs musl headers for the
|
||||
# target arch via xx-apk.
|
||||
|
||||
# =============================================================================
|
||||
# xx: Dockerfile cross-compilation helpers (provides xx-clang, xx-apk, etc.)
|
||||
# =============================================================================
|
||||
# renovate: datasource=docker depName=tonistiigi/xx versioning=docker
|
||||
FROM --platform=$BUILDPLATFORM tonistiigi/xx:1.10.0@sha256:40fe21f44bb8cddf1eb1226db190d0a984118f62ee02a91b77d99448d28264a6 AS xx
|
||||
|
||||
# =============================================================================
|
||||
# Stage 1: Build Tailscale combined binary (cross-compiled, runs natively)
|
||||
# =============================================================================
|
||||
FROM --platform=$BUILDPLATFORM golang:1.26.3-alpine@sha256:91eda9776261207ea25fd06b5b7fed8d397dd2c0a283e77f2ab6e91bfa71079d AS builder
|
||||
FROM --platform=$BUILDPLATFORM golang:1.27.4-alpine@sha256:70bd7ddea8b6cbe5d6943cde279d6b67feb10cc924fb9100d1d8757c1575b280 AS builder
|
||||
|
||||
# renovate: datasource=github-releases depName=tailscale packageName=tailscale/tailscale
|
||||
ARG TAILSCALE_VERSION=v1.98.3
|
||||
# renovate: datasource=github-releases depName=tailscale packageName=tailscale/tailscale versioning=semver
|
||||
ARG TAILSCALE_VERSION=v1.104.6
|
||||
|
||||
# Provided automatically by buildx for the target platform.
|
||||
ARG TARGETOS
|
||||
@@ -40,6 +53,23 @@ RUN git clone --depth 1 --branch ${TAILSCALE_VERSION} \
|
||||
|
||||
WORKDIR /src/tailscale
|
||||
|
||||
# Inject a stderr verbosity filter into the tailscaled package.
|
||||
#
|
||||
# With logtail compiled out (ts_omit_logtail), tailscaled never installs
|
||||
# logpolicy (see `if buildfeatures.HasLogTail` in cmd/tailscaled/tailscaled.go),
|
||||
# so log output goes raw to stderr: the [v1]/[v2] verbosity tags embedded in
|
||||
# messages are neither parsed nor filtered, and --verbose has NO effect. The
|
||||
# result is constant log spam in the RouterOS container log (filter
|
||||
# "Accept: TCP" verdicts, "netcheck: [v1] report", "wg: [v2]" handshakes and
|
||||
# keepalives) — see tailscale/tailscale#12158 and #1548.
|
||||
#
|
||||
# The injected file (build-tagged ts_omit_logtail, so it's a no-op if logtail
|
||||
# is ever re-enabled) registers a log writer in init() that drops lines
|
||||
# carrying a [v1]+ tag, restoring the equivalent of logtail's StderrLevel=0
|
||||
# default. Setting TS_LOG_VERBOSITY=1 (or higher) in the container environment
|
||||
# disables the filter at runtime for debugging — no rebuild needed.
|
||||
COPY patches/stderr_verbosity_filter.go cmd/tailscaled/
|
||||
|
||||
# Build a minimal combined binary (tailscale CLI + tailscaled daemon in one file).
|
||||
#
|
||||
# Tag strategy — ALLOWLIST, not blocklist:
|
||||
@@ -60,36 +90,141 @@ WORKDIR /src/tailscale
|
||||
# dns — MagicDNS; configure MikroTik DNS to forward
|
||||
# *.ts.net → 100.100.100.100; use --no-dns daemon
|
||||
# flag to skip writing /etc/resolv.conf
|
||||
# udptransport — REQUIRED for direct (non-DERP) peer connections. Added
|
||||
# as a separate tag in v1.104.0; when omitted, magicsock
|
||||
# never runs its UDP receive loops and ALL peer traffic
|
||||
# is relayed over DERP. Symptom on omission: health
|
||||
# warning "The MagicSock function ReceiveIPv4 is not
|
||||
# running" (magicsock-receive-func-error).
|
||||
# nattraversal — STUN, disco hole punching, UDP peer relay client. Also
|
||||
# new in v1.104.0; without it direct UDP only works to
|
||||
# peers with directly reachable endpoints. Depends on
|
||||
# udptransport.
|
||||
# portmapper — NAT-PMP / PCP / UPnP to punch through upstream NAT
|
||||
# (depends on nattraversal)
|
||||
# listenrawdisco — raw sockets for more robust disco/NAT-traversal
|
||||
# (depends on udptransport)
|
||||
# health — health subsystem required by 'tailscale status'
|
||||
# cachenetmap — cache netmap on disk for faster reconnect after reboot
|
||||
# IMPORTANT: mount cache dir on tmpfs, not internal flash
|
||||
# iptables — Linux iptables support for routing rules
|
||||
# unixsocketidentity — REQUIRED for the CLI to talk to the daemon. Without it,
|
||||
# the localapi can't verify a request arrived over the
|
||||
# trusted unix socket, so PermitRead/PermitWrite are
|
||||
# always false and EVERY CLI call (status, up, set, ...)
|
||||
# returns "access denied" (tailscale/tailscale#17873).
|
||||
# ipnbus — IPN bus watch. Without it, 'tailscale up' cannot wait
|
||||
# for completion: it fires config at the daemon and
|
||||
# returns immediately ("built with ts_omit_ipnbus; not
|
||||
# waiting for completion") WITHOUT printing the auth URL
|
||||
# or confirming success. Including it makes interactive
|
||||
# 'up' behave normally (blocks, prints login URL).
|
||||
# netstack — gVisor userspace network stack. Counter-intuitively
|
||||
# REQUIRED even though the router uses a real kernel TUN
|
||||
# (NOT --tun=userspace-networking). In v1.98.5 the
|
||||
# 100.100.100.100:53 MagicDNS listener is served ONLY by
|
||||
# netstack's handleLocalPackets, installed via
|
||||
# PreFilterPacketOutboundToWireGuardNetstackIntercept.
|
||||
# The non-netstack "engine" interceptor that the wrap.go
|
||||
# comments claim handles quad-100 "if netstack is not
|
||||
# installed" does NOT actually do so on Linux (its body
|
||||
# only reflects loopback on darwin/ios/plan9, else
|
||||
# Accept). So with ts_omit_netstack, NOTHING absorbs
|
||||
# packets to 100.100.100.100: queries fall through to
|
||||
# WireGuard, no peer owns that IP, and even tailnet-name
|
||||
# resolution (and 'ping host.tailnet.ts.net') times out.
|
||||
# The 'dns' tag links the resolver but nothing routes
|
||||
# packets to it without netstack — the two tags are
|
||||
# independent (dns has no Dep on netstack). Omitting
|
||||
# netstack ALSO triggered a panic("unreachable") in
|
||||
# net/tstun.invertGSOChecksum on the exit-node inject
|
||||
# path (HasNetstack=const false made the guard always
|
||||
# panic); enabling netstack makes that guard dead code,
|
||||
# fixing the crash as a side effect. Cost (arm64, vs a
|
||||
# netstack-omitted build): ~+0.5 MB extracted on flash
|
||||
# and ~+2.3 MB resident RAM after UPX decompression —
|
||||
# measured, acceptable for a 16 MB-flash router.
|
||||
# gro — Generic Receive Offload (perf). Depends on netstack;
|
||||
# pulled in with it. Small, and improves throughput on
|
||||
# the netstack DNS/inject path.
|
||||
# peerapiserver — REQUIRED to be a functional exit node. In v1.98.5
|
||||
# 'advertiseexitnode' DECLARES a dependency on
|
||||
# peerapiserver (featuretags.go Deps, "to run the ExitDNS
|
||||
# server"), but this build's allowlist works by stripping
|
||||
# individual ts_omit_ tags and does NOT re-resolve Deps —
|
||||
# so featuretags --min still emitted ts_omit_peerapiserver
|
||||
# and our advertiseexitnode opt-in alone left it omitted.
|
||||
# peerapiserver gates the entire PeerAPI HTTP server,
|
||||
# including the /dns-query DoH endpoint (peerapi.go,
|
||||
# guarded by buildfeatures.HasPeerAPIServer). Without it
|
||||
# initPeerAPIListenerLocked() returns early: the node
|
||||
# never advertises the PeerAPIDNS service, so exit-node
|
||||
# CLIENTS' exitNodeCanProxyDNS(thisNode) returns false.
|
||||
# With no tailnet global nameserver configured, the
|
||||
# client's resolver then has an empty Routes["."] and
|
||||
# returns an INSTANT authoritative SERVFAIL locally
|
||||
# (forwarder.go servfailResponse, aa=1, 0 ms, no I/O) —
|
||||
# i.e. devices using this router as their exit node could
|
||||
# not resolve PUBLIC names. Including peerapiserver makes
|
||||
# the node serve the exit-node DoH DNS proxy, so clients
|
||||
# get public DNS automatically (the normal exit-node
|
||||
# behavior) with no tailnet DNS config required.
|
||||
# peerapiserver has NO Deps and pulls in no large
|
||||
# subsystems — a small addition. (outboundproxy is NOT
|
||||
# needed for this and stays omitted.)
|
||||
#
|
||||
# Everything else remains omitted, including (rationale):
|
||||
# clientupdate — updates managed via Docker image rebuild
|
||||
# clientupdate — DELIBERATELY removed. The built-in updater would download
|
||||
# the FULL official upstream tailscale binary (tens of MB,
|
||||
# with all features) directly onto the device, defeating the
|
||||
# entire point of this minimal build and risking filling the
|
||||
# 16 MB flash. It also can't update a binary baked into a
|
||||
# read-only container image. Updates are instead delivered by
|
||||
# rebuilding/republishing this image (CI) and pulling the new
|
||||
# image only when it actually changed (see the RouterOS
|
||||
# update script). This keeps the on-device footprint minimal
|
||||
# and the update path controlled, reproducible, and flash-safe.
|
||||
# cachenetmap — DELIBERATELY omitted. It ONLY persists the netmap to disk so
|
||||
# the node can come online from the last-known config after a
|
||||
# COLD START while the control plane is simultaneously
|
||||
# unreachable. The in-memory netmap is NOT gated by this tag:
|
||||
# a running daemon that loses its control connection keeps its
|
||||
# map and can still reach known peers (data path is direct
|
||||
# WireGuard/DERP, not via control). The only loss is the narrow
|
||||
# reboot-during-control-outage case. In exchange we avoid disk
|
||||
# writes on every netmap delta (frequent on busy tailnets),
|
||||
# which is exactly the flash wear we want to avoid.
|
||||
# logtail — no persistent log writes to flash; also pass
|
||||
# --no-logs-no-support at runtime
|
||||
# netstack+gro — userspace networking; router uses kernel TUN
|
||||
# dnsresolvecache — persists DNS resolutions to disk; flash writes for a
|
||||
# marginal cold-start benefit
|
||||
# ssh — not needed; access via MikroTik SSH + tailscale CLI
|
||||
# all GUI/desktop/cloud/k8s features — irrelevant for a headless router
|
||||
#
|
||||
# NOTE: netstack/gro are NOT in this omit list — see the opted-in section above
|
||||
# for why MagicDNS quad-100 serving structurally requires them in v1.98.5.
|
||||
|
||||
# The omit list is wrapped in commas so each pattern matches a WHOLE tag
|
||||
# (",ts_omit_dns," must not eat the prefix of ",ts_omit_dnsresolvecache,").
|
||||
RUN mkdir -p /out && \
|
||||
ALL_OMIT=$(GOOS= GOARCH= go run ./cmd/featuretags --min --add=osrouter) && \
|
||||
TAGS=$(echo "ts_include_cli,${ALL_OMIT}" | \
|
||||
TAGS=$(echo ",ts_include_cli,${ALL_OMIT}," | \
|
||||
sed \
|
||||
-e 's/ts_omit_advertiseexitnode,\{0,1\}//g' \
|
||||
-e 's/ts_omit_advertiseroutes,\{0,1\}//g' \
|
||||
-e 's/ts_omit_useexitnode,\{0,1\}//g' \
|
||||
-e 's/ts_omit_useroutes,\{0,1\}//g' \
|
||||
-e 's/ts_omit_dns,\{0,1\}//g' \
|
||||
-e 's/ts_omit_portmapper,\{0,1\}//g' \
|
||||
-e 's/ts_omit_listenrawdisco,\{0,1\}//g' \
|
||||
-e 's/ts_omit_health,\{0,1\}//g' \
|
||||
-e 's/ts_omit_cachenetmap,\{0,1\}//g' \
|
||||
-e 's/ts_omit_iptables,\{0,1\}//g' \
|
||||
-e 's/,$//' \
|
||||
-e 's/,ts_omit_advertiseexitnode,/,/' \
|
||||
-e 's/,ts_omit_advertiseroutes,/,/' \
|
||||
-e 's/,ts_omit_useexitnode,/,/' \
|
||||
-e 's/,ts_omit_useroutes,/,/' \
|
||||
-e 's/,ts_omit_dns,/,/' \
|
||||
-e 's/,ts_omit_udptransport,/,/' \
|
||||
-e 's/,ts_omit_nattraversal,/,/' \
|
||||
-e 's/,ts_omit_portmapper,/,/' \
|
||||
-e 's/,ts_omit_listenrawdisco,/,/' \
|
||||
-e 's/,ts_omit_health,/,/' \
|
||||
-e 's/,ts_omit_iptables,/,/' \
|
||||
-e 's/,ts_omit_unixsocketidentity,/,/' \
|
||||
-e 's/,ts_omit_ipnbus,/,/' \
|
||||
-e 's/,ts_omit_netstack,/,/' \
|
||||
-e 's/,ts_omit_gro,/,/' \
|
||||
-e 's/,ts_omit_peerapiserver,/,/' \
|
||||
-e 's/^,//' -e 's/,$//' \
|
||||
) && \
|
||||
echo "Build tags: ${TAGS}" && \
|
||||
# Map Docker's TARGETARCH/TARGETVARIANT to Go's GOARCH/GOARM.
|
||||
@@ -117,8 +252,37 @@ RUN mkdir -p /out && \
|
||||
# Expected: ~14 MB raw → ~3.8 MB compressed (with -gcflags=all=-l)
|
||||
RUN upx --lzma --best /out/tailscale.combined
|
||||
|
||||
# Lay out the final /usr/local/bin HERE (binary + argv[0] symlinks) so the final
|
||||
# stage can bring it in with a SINGLE COPY layer. Creating the symlinks with a
|
||||
# `RUN` in the final scratch stage instead would force overlayfs to copy-up the
|
||||
# whole directory — duplicating the ~3 MB binary into another layer and roughly
|
||||
# doubling the extracted on-disk size on RouterOS (overlay layers are extracted
|
||||
# separately). Building it in one place keeps it to one copy.
|
||||
RUN mkdir -p /out/usrlocalbin && \
|
||||
mv /out/tailscale.combined /out/usrlocalbin/tailscale.combined && \
|
||||
ln -s /usr/local/bin/tailscale.combined /out/usrlocalbin/tailscale && \
|
||||
ln -s /usr/local/bin/tailscale.combined /out/usrlocalbin/tailscaled
|
||||
|
||||
# Entrypoint wrapper: enable IP forwarding inside the container's network
|
||||
# namespace, then exec tailscaled. tailscaled does NOT reliably enable IPv6
|
||||
# forwarding itself in a container netns ("IPv6 forwarding is disabled" warning),
|
||||
# which silently breaks advertised IPv6 subnet routes. The sysctls ARE writable
|
||||
# from inside a RouterOS container, so we set both here. Written in the builder
|
||||
# stage so it ships in the same single /usr/local/bin COPY layer (preserves the
|
||||
# overlayfs single-copy property). `exec` keeps tailscaled as PID 1.
|
||||
RUN printf '%s\n' \
|
||||
'#!/bin/sh' \
|
||||
'# Enable IPv4/IPv6 forwarding. Required for advertised subnet routes and' \
|
||||
'# exit-node functionality.' \
|
||||
'for f in /proc/sys/net/ipv4/ip_forward /proc/sys/net/ipv6/conf/all/forwarding; do' \
|
||||
' if [ -w "$f" ]; then echo 1 > "$f" 2>/dev/null || echo "warn: could not write $f"; fi' \
|
||||
'done' \
|
||||
'exec /usr/local/bin/tailscaled "$@"' \
|
||||
> /out/usrlocalbin/entrypoint.sh && \
|
||||
chmod +x /out/usrlocalbin/entrypoint.sh
|
||||
|
||||
# =============================================================================
|
||||
# Stage 2: Custom minimal busybox
|
||||
# Stage 2: Custom minimal busybox (cross-compiled, runs natively on build host)
|
||||
# =============================================================================
|
||||
# The official busybox:musl image ships all ~404 applets at ~1.24 MB. For a
|
||||
# debug shell on a flash-constrained router we only need ~100 applets, so we
|
||||
@@ -135,15 +299,56 @@ RUN upx --lzma --best /out/tailscale.combined
|
||||
# acceptable for an occasional debug shell. RouterOS stores the EXTRACTED
|
||||
# rootfs on disk (overlayfs), so the ~190 kB UPX saving is real on-disk space.
|
||||
#
|
||||
# This stage runs on the TARGET platform (no --platform override): gcc then
|
||||
# produces native target-arch binaries directly. Under buildx this is
|
||||
# transparently emulated via binfmt/QEMU for non-native targets.
|
||||
FROM alpine:3.21.7@sha256:48b0309ca019d89d40f670aa1bc06e426dc0931948452e8491e3d65087abc07d AS busybox
|
||||
# This stage runs NATIVELY on the build host (--platform=$BUILDPLATFORM) and
|
||||
# cross-compiles busybox for the target architecture using clang+lld via the
|
||||
# tonistiigi/xx helpers. This eliminates QEMU emulation from the busybox build,
|
||||
# which was the main source of slowness for arm64/arm/v7 targets.
|
||||
#
|
||||
# Cross-compilation setup:
|
||||
# - xx-apk installs musl-dev and linux-headers for the TARGET arch under
|
||||
# /<triple> (a secondary sysroot), while clang/lld/upx/make stay native.
|
||||
# - xx-clang --setup-target-triple creates <triple>-clang / <triple>-cc
|
||||
# aliases in PATH that busybox's Makefile picks up via CROSS_COMPILE.
|
||||
# - Busybox make receives:
|
||||
# CROSS_COMPILE=<triple>- → picks up <triple>-clang (from xx aliases)
|
||||
# CC=clang → use clang (aliased target via CROSS_COMPILE)
|
||||
# HOSTCC=gcc → compile host helper tools with native gcc
|
||||
# - upx (native x86_64 binary) can compress target-arch binaries since UPX
|
||||
# operates on the ELF file format regardless of the target ISA.
|
||||
#
|
||||
# Applet symlink probing: for native-arch builds the probe runs directly;
|
||||
# for cross-compiled binaries we use QEMU user-mode emulation (from binfmt)
|
||||
# only for this one lightweight probe step (busybox --help per applet), not
|
||||
# for the compile itself. The probe can alternatively be skipped by using
|
||||
# a pre-enumerated applet list, but the current approach is simpler.
|
||||
FROM --platform=$BUILDPLATFORM alpine:3.24.4@sha256:f59abe656b692d901e184be3445e084786602108599d2a51d229c0f5a48c71bf AS busybox
|
||||
|
||||
# Copy xx cross-compilation helpers (xx-clang, xx-apk, xx-info, etc.)
|
||||
COPY --from=xx / /
|
||||
|
||||
# renovate: datasource=docker depName=busybox versioning=docker
|
||||
ARG BUSYBOX_VERSION=1.37.0
|
||||
ARG BUSYBOX_VERSION=1.38.0
|
||||
|
||||
RUN apk add --no-cache build-base linux-headers wget bzip2 perl upx
|
||||
# Target platform ARGs (provided automatically by buildx).
|
||||
ARG TARGETPLATFORM
|
||||
ARG TARGETARCH
|
||||
ARG TARGETVARIANT
|
||||
|
||||
# Native build tools (clang/lld for cross-compiling; gcc/make/upx run natively).
|
||||
# xx-apk installs the target-arch sysroot: musl-dev (C library headers + CRT),
|
||||
# gcc (provides crtbeginS.o/crtendS.o and libgcc needed by clang on Alpine),
|
||||
# and linux-headers (required by busybox for <linux/*.h> / <net/*.h>).
|
||||
RUN apk add --no-cache \
|
||||
clang \
|
||||
lld \
|
||||
llvm \
|
||||
gcc \
|
||||
make \
|
||||
wget \
|
||||
bzip2 \
|
||||
perl \
|
||||
upx && \
|
||||
xx-apk add --no-cache musl-dev gcc linux-headers
|
||||
|
||||
RUN wget -q https://busybox.net/downloads/busybox-${BUSYBOX_VERSION}.tar.bz2 \
|
||||
&& tar xf busybox-${BUSYBOX_VERSION}.tar.bz2
|
||||
@@ -151,7 +356,34 @@ WORKDIR /busybox-${BUSYBOX_VERSION}
|
||||
|
||||
# allnoconfig = every feature OFF; then enable only the curated applet set.
|
||||
COPY busybox-applets.config /tmp/applets.config
|
||||
RUN make allnoconfig && \
|
||||
# Set up xx cross-compiler aliases (<triple>-clang, <triple>-cc, etc.) and
|
||||
# build busybox.
|
||||
#
|
||||
# Key make variables:
|
||||
# ARCH — busybox ARCH; must match the cross-target, not the build
|
||||
# host. busybox's Makefile would otherwise read SUBARCH from
|
||||
# `uname -m` (the BUILD host's arch) which is wrong when
|
||||
# cross-compiling. We map TARGETARCH to busybox's arch name.
|
||||
# busybox uses -include arch/$(ARCH)/Makefile; missing arch
|
||||
# dirs are silently ignored, so any value is safe.
|
||||
# CC — busybox defaults to $(CROSS_COMPILE)gcc. We override CC to
|
||||
# the full <triple>-clang path so it resolves to the xx alias
|
||||
# (which sets --target and --sysroot for the cross-compiler).
|
||||
# Setting CC= avoids needing a <triple>-gcc symlink.
|
||||
# HOSTCC — native compiler for host-side build tools (scripts/kconfig,
|
||||
# gen_build_files, etc.); must NOT be the cross-compiler.
|
||||
# SKIP_STRIP — defer stripping to after symlink probing (we strip below
|
||||
# with llvm-strip, which handles any target ELF arch).
|
||||
RUN xx-clang --setup-target-triple && \
|
||||
CROSS=$(xx-info triple) && \
|
||||
# Map TARGETARCH to the busybox ARCH value.
|
||||
case "${TARGETARCH}" in \
|
||||
amd64) BUSYBOX_ARCH=x86_64 ;; \
|
||||
arm64) BUSYBOX_ARCH=aarch64 ;; \
|
||||
arm) BUSYBOX_ARCH=arm ;; \
|
||||
*) BUSYBOX_ARCH=${TARGETARCH} ;; \
|
||||
esac && \
|
||||
make allnoconfig ARCH="${BUSYBOX_ARCH}" && \
|
||||
while read -r sym; do \
|
||||
case "$sym" in ''|\#*) continue ;; esac; \
|
||||
if grep -q "^# CONFIG_${sym} is not set" .config; then \
|
||||
@@ -160,9 +392,15 @@ RUN make allnoconfig && \
|
||||
echo "CONFIG_${sym}=y" >> .config; \
|
||||
fi; \
|
||||
done < /tmp/applets.config && \
|
||||
yes "" | make oldconfig >/dev/null 2>&1 && \
|
||||
make -j"$(nproc)" >/dev/null 2>&1 && \
|
||||
strip busybox
|
||||
yes "" | make oldconfig ARCH="${BUSYBOX_ARCH}" >/dev/null 2>&1 && \
|
||||
make -j"$(nproc)" \
|
||||
ARCH="${BUSYBOX_ARCH}" \
|
||||
CROSS_COMPILE="${CROSS}-" \
|
||||
CC="${CROSS}-clang" \
|
||||
HOSTCC=gcc \
|
||||
SKIP_STRIP=y \
|
||||
>/dev/null 2>&1 && \
|
||||
llvm-strip busybox
|
||||
|
||||
# Lay out a minimal rootfs with busybox + an applet symlink per applet.
|
||||
# Symlinks (argv[0] dispatch) are how busybox selects an applet and make the
|
||||
@@ -172,6 +410,10 @@ RUN make allnoconfig && \
|
||||
# for non-applet symbols like FEATURE_* / STATIC, which we filter out).
|
||||
# We generate symlinks from the UNCOMPRESSED binary (so the probe is reliable),
|
||||
# then UPX-compress the binary in place afterwards.
|
||||
#
|
||||
# Note: probing cross-compiled binaries requires binfmt/QEMU user-mode. This
|
||||
# is only a lightweight per-applet help-flag check, not a full emulated build.
|
||||
# If QEMU is unavailable in CI, replace the probe with a static applet list.
|
||||
RUN mkdir -p /rootfs/bin && \
|
||||
grep '^CONFIG_.*=y' .config \
|
||||
| sed -e 's/^CONFIG_//' -e 's/=y$//' \
|
||||
@@ -211,12 +453,10 @@ COPY --from=busybox /rootfs/ /
|
||||
# CA certificates (needed to reach Tailscale coordination server)
|
||||
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
|
||||
|
||||
# Combined Tailscale binary
|
||||
COPY --from=builder /out/tailscale.combined /usr/local/bin/tailscale.combined
|
||||
|
||||
# Symlinks: combined binary behavior switches on argv[0]
|
||||
RUN ["/bin/busybox", "ln", "-s", "/usr/local/bin/tailscale.combined", "/usr/local/bin/tailscale"]
|
||||
RUN ["/bin/busybox", "ln", "-s", "/usr/local/bin/tailscale.combined", "/usr/local/bin/tailscaled"]
|
||||
# Combined Tailscale binary + its argv[0] symlinks, in a single layer (built in
|
||||
# the builder stage to avoid overlayfs copy-up duplicating the binary — see the
|
||||
# builder stage comment).
|
||||
COPY --from=builder /out/usrlocalbin/ /usr/local/bin/
|
||||
|
||||
# Ensure /usr/local/bin and busybox dirs are on PATH for interactive shells
|
||||
ENV PATH=/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
|
||||
@@ -226,18 +466,19 @@ ENV PATH=/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
|
||||
#
|
||||
# /var/lib/tailscale — persistent state (authkey, node identity)
|
||||
# → bind-mount to MikroTik disk storage
|
||||
# → survives reboots, written infrequently
|
||||
#
|
||||
# /var/lib/tailscale/cache — netmap cache (cachenetmap feature)
|
||||
# → mount as tmpfs so it never touches flash
|
||||
# → speeds up reconnect but is recreatable
|
||||
# → survives reboots, written infrequently (only on
|
||||
# auth / key rotation / prefs change)
|
||||
# → netmap is NOT cached to disk (cachenetmap is
|
||||
# omitted), so this dir sees no per-netmap writes
|
||||
#
|
||||
# /var/run/tailscale — runtime socket dir
|
||||
# → tmpfs, lost on reboot (expected)
|
||||
# -----------------------------------------------------------------------------
|
||||
VOLUME ["/var/lib/tailscale"]
|
||||
|
||||
ENTRYPOINT ["/usr/local/bin/tailscaled"]
|
||||
# entrypoint.sh enables IP forwarding (incl. IPv6) in the container netns, then
|
||||
# exec's tailscaled with the CMD flags below as its arguments.
|
||||
ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
|
||||
|
||||
# Default flags:
|
||||
# --no-logs-no-support disables logtail uploads (logtail binary code is
|
||||
@@ -246,7 +487,8 @@ ENTRYPOINT ["/usr/local/bin/tailscaled"]
|
||||
# to write log files)
|
||||
# --state persistent node identity / authkey storage
|
||||
# --socket CLI communication socket (on tmpfs)
|
||||
# --statedir where cache and other runtime files land
|
||||
# --statedir var root (derpmap cache, certs, etc.); no netmap
|
||||
# disk cache here since cachenetmap is omitted
|
||||
CMD ["--no-logs-no-support", \
|
||||
"--state=/var/lib/tailscale/tailscaled.state", \
|
||||
"--socket=/var/run/tailscale/tailscaled.sock", \
|
||||
|
||||
@@ -7,6 +7,45 @@ A minimal Tailscale Docker image built for MikroTik routers running
|
||||
16 MB internal flash. Built from source with only router-relevant features
|
||||
included.
|
||||
|
||||
> Disclaimer: This project has been largely vibe-coded, but I stand behind design and implementation choices made.
|
||||
|
||||
- **~4 MB** extracted rootfs (`FROM scratch` + UPX'd Tailscale binary + a custom
|
||||
static busybox debug shell).
|
||||
- **Multi-arch**: amd64, arm64, arm/v7 — one tag, RouterOS pulls the right one.
|
||||
- **No built-in updater** (it would pull the full upstream binary and wear
|
||||
flash); updates are delivered by CI and pulled only when the image actually
|
||||
changed.
|
||||
- **Flash-wear conscious**: minimal persistent state, no netmap disk-caching,
|
||||
tmpfs for scratch and runtime.
|
||||
|
||||
## Motivation
|
||||
|
||||
There is no built-in Tailscale integration in MikroTik, and other solutions
|
||||
feel underwhelming. I've used Fluent-networks' tailscale-mikrotik until now,
|
||||
but that basically forced me to connect external storage to my router
|
||||
just to use Tailscale. This approach, while works, is fragile, wasteful
|
||||
and overcomplicated, so I decided to do better one myself.
|
||||
|
||||
| | **This project** | Fluent-networks/tailscale-mikrotik |
|
||||
|---|---|---|
|
||||
| Size | **~4 MB** | ~106 MB |
|
||||
| Size reduction technique | **Minimal container with custom Tailscale and Busybox builds, compressed by UPX** | Alpine Linux base, Tailscale binary compressed by UPX on build, but auto-update completely nullifies that on first launch |
|
||||
| Update mechanism | **Automatically released optimized container images with new Tailscale versions, scheduled script updating deployment on new version** | None, opt-in Tailscale built-in auto-update downloading official binaries |
|
||||
| Flash wear | **Write-heavy functionality compiled out, suitable for low-endurance flash chips** | High, constant netmap cache updates |
|
||||
| Stability | **Immutable container** | Tailscale app can update on its own |
|
||||
| Features | **Only router-useful Tailscale features compiled, Busybox providing shell and utils** | Full tailscale, OpenSSH server, Bash, IPTables |
|
||||
|
||||
## Documentation
|
||||
|
||||
- **[Usage](docs/USAGE.md)** — deploy the published image on a MikroTik router
|
||||
and operate it (networking, auth, MagicDNS, automatic updates). Start here if
|
||||
you just want it running.
|
||||
- **[Development](docs/DEVELOPMENT.md)** — build the image, test it locally, bump
|
||||
the Tailscale version, and cut releases.
|
||||
- **[Design & rationale](docs/DESIGN.md)** — size optimizations, the feature
|
||||
allowlist, why certain features are deliberately removed, flash-wear
|
||||
protection, and the versioning / release / update architecture.
|
||||
|
||||
## Supported architectures
|
||||
|
||||
| Docker platform | RouterOS arch | Example devices |
|
||||
@@ -15,371 +54,25 @@ included.
|
||||
| `linux/arm64` | arm64 | RB5009, CCR2004/2116/2216, hAP ax³, L009, Chateau |
|
||||
| `linux/arm/v7` | arm (ARMv7) | hAP ac², RB3011, RB4011, RB1100AHx4 |
|
||||
|
||||
A single Dockerfile builds all three. The Go binary is **cross-compiled** (the
|
||||
builder stage runs natively on the host for speed), while the busybox stage and
|
||||
final image are built for the target platform (via `buildx` + QEMU/binfmt for
|
||||
non-native targets).
|
||||
ARMv5 (hEX Refresh / hAP ax S) is **not** supported — see
|
||||
[DESIGN.md](docs/DESIGN.md#architecture-support).
|
||||
|
||||
**ARMv5 is not supported** (hEX Refresh / hAP ax S, EN7562CT CPU — RouterOS
|
||||
calls these `arm32v5`). ARMv5 has no Alpine/musl base image, so it cannot use
|
||||
this image's musl + `scratch` design; it would require a glibc (Debian) base
|
||||
and produce a substantially larger image (~50 MB+ vs ~4 MB). If you need it,
|
||||
that's a separate build, not just a `--platform` change.
|
||||
## Quick start
|
||||
|
||||
## Image size
|
||||
- **Run it on a router:** follow **[docs/USAGE.md](docs/USAGE.md)** — it deploys
|
||||
the prebuilt image, no build needed.
|
||||
- **Build it yourself:** `./build.sh` (needs docker buildx + QEMU for
|
||||
cross-arch); details in **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)**.
|
||||
|
||||
On-disk footprint once extracted (this is what matters — RouterOS stores the
|
||||
**extracted** rootfs on disk via overlayfs, not the compressed layers):
|
||||
## Repository layout
|
||||
|
||||
| Component | On-disk size |
|
||||
| Path | Purpose |
|
||||
|---|---|
|
||||
| tailscale.combined (UPX-compressed) | ~3.84 MB |
|
||||
| custom static busybox (UPX, ~100 applets) | ~229 kB |
|
||||
| CA certificates | ~218 kB |
|
||||
| **Total extracted rootfs** | **~4.1 MB** |
|
||||
|
||||
(The compressed image / transfer tarball is ~4.3 MB.)
|
||||
|
||||
The binary is built with Tailscale's `--extra-small` feature tag set as the
|
||||
baseline. Features are opted in explicitly — any new feature Tailscale adds
|
||||
in a future release stays omitted until deliberately added to the Dockerfile.
|
||||
|
||||
### Size optimizations applied
|
||||
|
||||
- **Feature allowlist** (`--extra-small` baseline + ~10 opt-ins) keeps the
|
||||
binary minimal and forward-safe against new Tailscale features.
|
||||
- **`-gcflags=all=-l`** disables function inlining across all packages,
|
||||
shrinking the compressed binary by ~600 kB. Inlining is a performance
|
||||
optimization only; disabling it does not affect correctness. The CPU cost
|
||||
is negligible for an I/O-bound router daemon.
|
||||
- **`-ldflags="-s -w"`** strips the symbol table and DWARF debug info.
|
||||
- **`-trimpath`** removes local filesystem paths from the binary.
|
||||
- **UPX `--lzma --best`** compresses the Tailscale binary (~14 MB → ~3.8 MB).
|
||||
- **Custom static busybox** — instead of the official `busybox:musl` image
|
||||
(all ~404 applets, ~1.24 MB), a static busybox is built from source with
|
||||
only ~100 curated applets (~420 kB), then UPX-compressed to ~229 kB on
|
||||
disk. The applet set is defined in
|
||||
[`busybox-applets.config`](busybox-applets.config).
|
||||
|
||||
**busybox UPX requires care.** UPX normally breaks busybox's standalone
|
||||
applet dispatch: the ash shell re-execs `/proc/self/exe` to run built-in
|
||||
applets, and UPX breaks that path so typed commands fail
|
||||
([upx#248](https://github.com/upx/upx/issues/248), closed as "invalid").
|
||||
We work around it by building **without** the standalone/nofork features
|
||||
and providing an explicit `/bin/<applet>` symlink farm. Commands then
|
||||
resolve via the normal `PATH` → symlink → `argv[0]` dispatch, which works
|
||||
under UPX. The cost is a `fork+exec` per command instead of a nofork
|
||||
internal call — fine for an occasional debug shell.
|
||||
|
||||
Because RouterOS stores the extracted rootfs on disk, UPX'ing busybox
|
||||
saves a real ~195 kB of flash (424 kB → 229 kB), not just transfer size.
|
||||
|
||||
The final image is built `FROM scratch` — there is no base distro layer.
|
||||
It contains only the busybox binary + applet symlinks, the CA bundle, and
|
||||
the Tailscale binary.
|
||||
|
||||
## Features included
|
||||
|
||||
| Feature | Why |
|
||||
|---|---|
|
||||
| `advertise-exit-node` | Run the router as a Tailscale exit node |
|
||||
| `advertise-routes` | Expose LAN subnets to the tailnet |
|
||||
| `use-exit-node` | Route the router's own traffic via a remote exit node |
|
||||
| `accept-routes` | Receive subnet routes from other tailnet nodes |
|
||||
| DNS / MagicDNS | Resolve `*.ts.net` names (see DNS section below) |
|
||||
| portmapper (NAT-PMP/PCP/UPnP) | Punch through upstream NAT |
|
||||
| listenrawdisco | Raw socket disco for better NAT traversal |
|
||||
| health | Powers `tailscale status` output |
|
||||
| cachenetmap | Cache network map for faster reconnect after reboot |
|
||||
| iptables | Linux iptables support for routing rules |
|
||||
| osrouter | Configure kernel network stack and routing tables |
|
||||
|
||||
## Features intentionally omitted
|
||||
|
||||
| Feature | Reason |
|
||||
|---|---|
|
||||
| `clientupdate` | Updates are managed by rebuilding the Docker image |
|
||||
| `logtail` | Would attempt persistent log writes; wear flash |
|
||||
| `netlog` | Network flow logging; separate concern |
|
||||
| `netstack` + `gro` | Userspace/gVisor networking; router uses kernel TUN |
|
||||
| `ssh` | Access via MikroTik SSH + `tailscale` CLI instead |
|
||||
| `linuxdnsfight` | inotify on `/etc/resolv.conf`; no systemd in container |
|
||||
| `networkmanager` / `resolved` / `dbus` / `sdnotify` | No systemd stack in container |
|
||||
| `drive` / `taildrop` / `webclient` | Not useful on a headless router |
|
||||
| All GUI / desktop / cloud / k8s features | Irrelevant |
|
||||
|
||||
## Volume layout
|
||||
|
||||
Three mount points, with different persistence requirements:
|
||||
|
||||
```
|
||||
/var/lib/tailscale persistent — node identity, auth state
|
||||
bind-mount to MikroTik disk storage
|
||||
written rarely (only on auth / key rotation)
|
||||
|
||||
/var/lib/tailscale/cache ephemeral — netmap cache
|
||||
mount as tmpfs to avoid flash writes
|
||||
recreated automatically on next connect
|
||||
|
||||
/var/run/tailscale ephemeral — daemon Unix socket
|
||||
mount as tmpfs
|
||||
lost on reboot, recreated on start
|
||||
```
|
||||
|
||||
Keeping the cache and socket directories on tmpfs prevents unnecessary
|
||||
flash wear while still allowing fast reconnect after reboot (the cache
|
||||
is repopulated from the Tailscale coordination server on first connect).
|
||||
|
||||
## Building
|
||||
|
||||
### All architectures at once
|
||||
|
||||
Use the helper script (requires `docker buildx` + QEMU/binfmt for non-native
|
||||
targets):
|
||||
|
||||
```sh
|
||||
# One-time: register emulators for cross-arch builds
|
||||
docker run --privileged --rm tonistiigi/binfmt --install arm64,arm
|
||||
|
||||
# Build all arches and load into local docker
|
||||
./build.sh
|
||||
|
||||
# Build all arches and also export per-arch tarballs into ./dist/
|
||||
./build.sh --tar
|
||||
|
||||
# Build a single arch
|
||||
./build.sh arm64
|
||||
./build.sh --tar armv7
|
||||
```
|
||||
|
||||
### Manual single-arch build
|
||||
|
||||
The architecture is selected via `buildx --platform`; the Dockerfile maps it to
|
||||
the correct `GOARCH`/`GOARM` automatically:
|
||||
|
||||
```sh
|
||||
docker buildx build --platform linux/arm64 --load -t mikrotik-tailscale:arm64 .
|
||||
docker buildx build --platform linux/arm/v7 --load -t mikrotik-tailscale:armv7 .
|
||||
docker buildx build --platform linux/amd64 --load -t mikrotik-tailscale:amd64 .
|
||||
```
|
||||
|
||||
To build for a different Tailscale version, add:
|
||||
|
||||
```sh
|
||||
--build-arg TAILSCALE_VERSION=v1.98.3
|
||||
```
|
||||
|
||||
### Notes
|
||||
|
||||
- The Go builder cross-compiles natively (fast); only the busybox stage runs
|
||||
under emulation for non-native targets.
|
||||
- The build prints the resolved target and Go build tags, e.g.:
|
||||
|
||||
```
|
||||
Cross-compiling: GOOS=linux GOARCH=arm64 GOARM=
|
||||
Build tags: ts_include_cli,ts_omit_ace,ts_omit_acme,...
|
||||
```
|
||||
|
||||
### Per-architecture image sizes
|
||||
|
||||
| Arch | Image |
|
||||
|---|---|
|
||||
| amd64 | ~4.2 MB |
|
||||
| arm64 | ~3.5 MB |
|
||||
| arm/v7 | ~3.5 MB |
|
||||
|
||||
## Running (local test)
|
||||
|
||||
```sh
|
||||
# Create a volume for persistent state
|
||||
docker volume create tailscale-state
|
||||
|
||||
# Start the daemon
|
||||
docker run -d \
|
||||
--name tailscale \
|
||||
--cap-add NET_ADMIN \
|
||||
--cap-add NET_RAW \
|
||||
--device /dev/net/tun \
|
||||
--tmpfs /var/lib/tailscale/cache \
|
||||
--tmpfs /var/run/tailscale \
|
||||
-v tailscale-state:/var/lib/tailscale \
|
||||
mikrotik-tailscale
|
||||
|
||||
# Authenticate (opens browser / prints auth URL)
|
||||
docker exec tailscale tailscale login
|
||||
|
||||
# Check status
|
||||
docker exec tailscale tailscale status
|
||||
|
||||
# Advertise a subnet
|
||||
docker exec tailscale tailscale set --advertise-routes=192.168.88.0/24
|
||||
|
||||
# Advertise as exit node
|
||||
docker exec tailscale tailscale set --advertise-exit-node
|
||||
```
|
||||
|
||||
Subnet routes and exit node advertisement must also be approved in the
|
||||
[Tailscale admin console](https://login.tailscale.com/admin/machines).
|
||||
|
||||
## Unattended authentication
|
||||
|
||||
For automated / headless deployment, use an auth key:
|
||||
|
||||
```sh
|
||||
docker exec tailscale tailscale up \
|
||||
--authkey=tskey-auth-<key> \
|
||||
--advertise-routes=192.168.88.0/24 \
|
||||
--advertise-exit-node
|
||||
```
|
||||
|
||||
Auth keys can be created in the Tailscale admin console under
|
||||
**Settings → Keys**. Use a reusable key tagged with a device tag for
|
||||
infrastructure nodes.
|
||||
|
||||
## MagicDNS
|
||||
|
||||
The binary includes DNS support but the daemon is started with
|
||||
`--no-logs-no-support`, which does not affect DNS. To use MagicDNS name
|
||||
resolution, configure MikroTik's DNS to forward `.ts.net` queries to
|
||||
Tailscale's magic DNS resolver:
|
||||
|
||||
```
|
||||
/ip dns static
|
||||
add name="ts.net" type=FWD forward-to=100.100.100.100 match-subdomain=yes
|
||||
```
|
||||
|
||||
This avoids writing to `/etc/resolv.conf` inside the container (which would
|
||||
happen if `--accept-dns` is passed to `tailscale up`). The container resolves
|
||||
Tailscale node names; the rest of the router uses its own DNS.
|
||||
|
||||
## Flash wear protection
|
||||
|
||||
Several measures are in place to avoid wearing out internal flash:
|
||||
|
||||
- `clientupdate` omitted from binary — no background update downloads
|
||||
- `logtail` omitted from binary — no log upload attempts
|
||||
- `--no-logs-no-support` passed to daemon — suppresses any remaining log
|
||||
buffering
|
||||
- `netmap` cache mounted on tmpfs — cache writes never reach flash
|
||||
- `/var/run/tailscale` socket on tmpfs — runtime files never reach flash
|
||||
- Only `/var/lib/tailscale/tailscaled.state` touches persistent storage,
|
||||
and it is written only when the node authenticates or rotates its key
|
||||
|
||||
## Upgrading
|
||||
|
||||
Version bumps (Tailscale, busybox, base image digests) are normally proposed
|
||||
automatically via Renovate — see
|
||||
[Dependency pinning & automated updates](#dependency-pinning--automated-updates).
|
||||
Merge the Renovate PR, then rebuild and redeploy.
|
||||
|
||||
The feature allowlist in the Dockerfile carries forward automatically across
|
||||
Tailscale versions — any new `ts_omit_*` tags introduced in a new release will
|
||||
be omitted by default.
|
||||
|
||||
To bump manually, edit `ARG TAILSCALE_VERSION` in the `Dockerfile` (so the pin
|
||||
stays in version control) and rebuild:
|
||||
|
||||
```sh
|
||||
./build.sh --tar # rebuild all arches at the pinned version
|
||||
# or, override at build time without editing the Dockerfile:
|
||||
docker buildx build --platform linux/arm64 \
|
||||
--build-arg TAILSCALE_VERSION=v1.100.0 \
|
||||
--load -t mikrotik-tailscale:arm64 .
|
||||
```
|
||||
|
||||
## Versioning & releases
|
||||
|
||||
Released images are versioned as:
|
||||
|
||||
```
|
||||
v<TAILSCALE_VERSION>-mt.<N>
|
||||
```
|
||||
|
||||
e.g. `v1.98.3-mt.1`. The two parts mean:
|
||||
|
||||
- **`v<TAILSCALE_VERSION>`** — the bundled Tailscale version (the "what's
|
||||
inside" identifier), taken from `ARG TAILSCALE_VERSION` in the Dockerfile.
|
||||
- **`mt.<N>`** — the local revision. It only changes on a *meaningful* release,
|
||||
never on a build-system-only rebuild.
|
||||
|
||||
### When a release happens
|
||||
|
||||
| Trigger | Result |
|
||||
|---|---|
|
||||
| Renovate bumps `TAILSCALE_VERSION` (merged to `main`) | CI **auto-creates** git tag `v<new>-mt.1` → image published |
|
||||
| You make a meaningful fix/change on the current Tailscale version | **You** create the next tag manually (`v<ts>-mt.2`, `mt.3`, …) → image published |
|
||||
| Dependency-only bump (Go / Alpine / busybox / Dockerfile syntax) | **No release.** Rides along with the next Tailscale bump or manual tag |
|
||||
|
||||
So routers only ever see a new release for Tailscale bumps or your deliberate
|
||||
fixes — build-system churn doesn't trigger updates.
|
||||
|
||||
Each published image is stamped with `org.opencontainers.image.version` equal to
|
||||
its full tag; this is the value the MikroTik update job compares against the
|
||||
registry to decide whether to recreate the container.
|
||||
|
||||
### How it's wired (Woodpecker)
|
||||
|
||||
- **`.woodpecker/release-tag.yaml`** — on push to `main`, parses
|
||||
`TAILSCALE_VERSION`; if no `v<ts>-mt.*` tag exists yet, creates and pushes
|
||||
`v<ts>-mt.1` (using the Gitea token from OpenBao). It never creates `mt.2+`.
|
||||
- **`.woodpecker/release.yaml`** — on a `v*-mt.*` tag push, builds the
|
||||
multi-arch manifest (amd64 + arm64 + arm/v7) and pushes it to
|
||||
`gitea.lumpiasty.xyz/lumpiasty/mikrotik-tailscale` as both `:<tag>` and
|
||||
`:stable`. Registry creds come from OpenBao (`secret/container-registry`).
|
||||
|
||||
### Cutting a manual release
|
||||
|
||||
```sh
|
||||
# fix something, commit to main, then:
|
||||
git tag -a v1.98.3-mt.2 -m "Fix X"
|
||||
git push origin v1.98.3-mt.2
|
||||
```
|
||||
|
||||
The tag push triggers the build+publish automatically.
|
||||
|
||||
## Dependency pinning & automated updates
|
||||
|
||||
All upstream dependencies are version-pinned for reproducible builds:
|
||||
|
||||
All versions are fully qualified (no floating `major.minor` tags):
|
||||
|
||||
| Dependency | Where | Pinned form |
|
||||
|---|---|---|
|
||||
| Go toolchain | `Dockerfile` `FROM golang:…` | full version tag + `@sha256` digest |
|
||||
| Alpine (busybox build base) | `Dockerfile` `FROM alpine:…` | full version tag + `@sha256` digest |
|
||||
| Tailscale | `Dockerfile` `ARG TAILSCALE_VERSION` | full git release tag |
|
||||
| busybox | `Dockerfile` `ARG BUSYBOX_VERSION` | full release version |
|
||||
| Renovate / OpenBao | `.woodpecker/renovate.yaml` `image:` | full version tag |
|
||||
|
||||
Updates are proposed automatically by [Renovate](https://docs.renovatebot.com/),
|
||||
run **self-hosted** from a Woodpecker cron pipeline (Woodpecker has no native
|
||||
Renovate support):
|
||||
|
||||
- `renovate.json` — repository rules. All dependencies follow the latest
|
||||
upstream releases (including major versions); each bump arrives as its own PR
|
||||
that the multi-arch build validates before you merge. Base image tags also
|
||||
get their `@sha256` digests refreshed via `pinDigests`. The one special rule:
|
||||
- `tailscale` only follows **stable** releases — Tailscale uses even minor
|
||||
versions for stable (`v1.98.x`) and odd for unstable (`v1.99.x`), so the
|
||||
rule filters to even minors.
|
||||
- `.woodpecker/renovate.yaml` — the scheduled job that runs `renovate/renovate`
|
||||
against this repo.
|
||||
|
||||
```sh
|
||||
# Renovate repo config
|
||||
docker run --rm -e RENOVATE_CONFIG_TYPE=repo -v "$PWD":/work -w /work \
|
||||
--entrypoint renovate-config-validator renovate/renovate
|
||||
|
||||
# Woodpecker pipeline
|
||||
docker run --rm -v "$PWD":/work -w /work \
|
||||
woodpeckerci/woodpecker-cli:v3 lint .woodpecker/renovate.yaml
|
||||
```
|
||||
|
||||
## References
|
||||
|
||||
- [Tailscale: Smaller binaries for embedded devices](https://tailscale.com/docs/how-to/set-up-small-tailscale)
|
||||
- [Renovate self-hosting](https://docs.renovatebot.com/getting-started/running/)
|
||||
- [Woodpecker cron jobs](https://woodpecker-ci.org/docs/usage/cron)
|
||||
- [MikroTik Container documentation](https://help.mikrotik.com/docs/display/ROS/Container)
|
||||
- [Tailscale subnet routers](https://tailscale.com/kb/1019/subnets)
|
||||
- [Tailscale exit nodes](https://tailscale.com/kb/1103/exit-nodes)
|
||||
| `Dockerfile` | Multi-stage, multi-arch build (cross-compiled Go + custom busybox) |
|
||||
| `busybox-applets.config` | Curated busybox applet set |
|
||||
| `patches/` | Source files injected into the Tailscale tree at build time (stderr verbosity filter) |
|
||||
| `build.sh` | Build all/one arch, optionally export per-arch tarballs |
|
||||
| `routeros/update-tailscale.rsc` | RouterOS auto-update script (digest compare + recreate) |
|
||||
| `.woodpecker/` | CI: Renovate cron, release tagging, multi-arch publish |
|
||||
| `renovate.json` | Dependency-update rules |
|
||||
| `docs/` | Tutorial and design docs |
|
||||
@@ -12,7 +12,8 @@
|
||||
#
|
||||
# Requirements:
|
||||
# - docker with buildx
|
||||
# - For non-native targets: binfmt/QEMU emulators registered, e.g.:
|
||||
# - For non-native targets: binfmt/QEMU emulators registered for the applet
|
||||
# symlink probe step (a minor step; the full C/Go compile is native):
|
||||
# docker run --privileged --rm tonistiigi/binfmt --install arm64,arm
|
||||
set -eu
|
||||
|
||||
|
||||
+614
@@ -0,0 +1,614 @@
|
||||
# Design & rationale
|
||||
|
||||
Why `mikrotik-tailscale` is built the way it is: size optimizations, the
|
||||
feature allowlist, deliberate omissions, flash-wear protection, and the
|
||||
versioning/release/update architecture.
|
||||
|
||||
For deployment, see [USAGE.md](USAGE.md); for building and releasing, see
|
||||
[DEVELOPMENT.md](DEVELOPMENT.md).
|
||||
|
||||
## Image size
|
||||
|
||||
On-disk footprint once extracted (this is what matters — RouterOS stores the
|
||||
**extracted** rootfs on disk via overlayfs, not the compressed layers).
|
||||
Measured flattened rootfs for the arm64 image:
|
||||
|
||||
| Component | On-disk size |
|
||||
|---|---|
|
||||
| `tailscale.combined` (UPX-compressed) | ~3.47 MB |
|
||||
| custom static busybox (UPX, ~100 applets) | ~218 kB |
|
||||
| CA certificates | ~213 kB |
|
||||
| **Total extracted rootfs** | **~3.9 MB** |
|
||||
|
||||
The `tailscale.combined` figure includes `netstack` (gVisor), which adds
|
||||
~0.5 MB on disk over a netstack-omitted build — a deliberate inclusion, see
|
||||
[Why netstack is required (even with a kernel TUN)](#why-netstack-is-required-even-with-a-kernel-tun).
|
||||
|
||||
(The compressed image / transfer tarball is ~3.8–4.3 MB depending on arch.)
|
||||
|
||||
| Arch | Image (compressed) |
|
||||
|---|---|
|
||||
| amd64 | ~4.3 MB |
|
||||
| arm64 | ~4.0 MB |
|
||||
| arm/v7 | ~4.0 MB |
|
||||
|
||||
On a deployed RouterOS device the container consumes **~4.2 MiB of flash**
|
||||
(measured by `free-hdd-space` delta). Note that `du` *inside* the container
|
||||
reports roughly double that (~8 MB) — that is RouterOS block-allocation
|
||||
rounding, **not** real usage or duplication; see
|
||||
[Avoiding overlayfs layer duplication](#avoiding-overlayfs-layer-duplication)
|
||||
for how to measure correctly.
|
||||
|
||||
The binary is built with Tailscale's `--extra-small` feature tag set as the
|
||||
baseline. Features are opted in explicitly — any new feature Tailscale adds
|
||||
in a future release stays omitted until deliberately added to the Dockerfile.
|
||||
|
||||
### Size optimizations applied
|
||||
|
||||
- **Feature allowlist** (`--extra-small` baseline + ~10 opt-ins) keeps the
|
||||
binary minimal and forward-safe against new Tailscale features.
|
||||
- **`-gcflags=all=-l`** disables function inlining across all packages,
|
||||
shrinking the compressed binary by ~600 kB. Inlining is a performance
|
||||
optimization only; disabling it does not affect correctness. The CPU cost
|
||||
is negligible for an I/O-bound router daemon.
|
||||
- **`-ldflags="-s -w"`** strips the symbol table and DWARF debug info.
|
||||
- **`-trimpath`** removes local filesystem paths from the binary.
|
||||
- **UPX `--lzma --best`** compresses the Tailscale binary (~14 MB → ~3.8 MB).
|
||||
- **Custom static busybox** — instead of the official `busybox:musl` image
|
||||
(all ~404 applets, ~1.24 MB), a static busybox is built from source with
|
||||
only ~100 curated applets (~420 kB), then UPX-compressed to ~229 kB on
|
||||
disk. The applet set is defined in
|
||||
[`busybox-applets.config`](../busybox-applets.config).
|
||||
|
||||
**busybox UPX requires care.** UPX normally breaks busybox's standalone
|
||||
applet dispatch: the ash shell re-execs `/proc/self/exe` to run built-in
|
||||
applets, and UPX breaks that path so typed commands fail
|
||||
([upx#248](https://github.com/upx/upx/issues/248), closed as "invalid").
|
||||
We work around it by building **without** the standalone/nofork features
|
||||
and providing an explicit `/bin/<applet>` symlink farm. Commands then
|
||||
resolve via the normal `PATH` → symlink → `argv[0]` dispatch, which works
|
||||
under UPX. The cost is a `fork+exec` per command instead of a nofork
|
||||
internal call — fine for an occasional debug shell.
|
||||
|
||||
Because RouterOS stores the extracted rootfs on disk, UPX'ing busybox
|
||||
saves a real ~195 kB of flash (424 kB → 229 kB), not just transfer size.
|
||||
|
||||
The final image is built `FROM scratch` — there is no base distro layer.
|
||||
It contains only the busybox binary + applet symlinks, the CA bundle, the
|
||||
Tailscale binary, and a tiny `entrypoint.sh`.
|
||||
|
||||
### Entrypoint: IP forwarding
|
||||
|
||||
`ENTRYPOINT` is a small `entrypoint.sh` that enables IPv4 and IPv6 forwarding
|
||||
(`net.ipv4.ip_forward`, `net.ipv6.conf.all.forwarding`) in the container's
|
||||
network namespace, then `exec`s `tailscaled` (so the daemon stays PID 1). This
|
||||
is necessary because `tailscaled` does **not** reliably enable IPv6 forwarding
|
||||
itself inside a container netns — it logs "IPv6 forwarding is disabled" and
|
||||
advertised IPv6 subnet routes silently fail. The sysctls are writable from
|
||||
inside a RouterOS container, so the entrypoint sets them directly; no
|
||||
host-side or `/container` configuration is required. The script is created in
|
||||
the builder stage so it ships in the same single `/usr/local/bin` `COPY` layer
|
||||
(preserving the [single-copy property](#avoiding-overlayfs-layer-duplication)).
|
||||
|
||||
### Avoiding overlayfs layer duplication
|
||||
|
||||
Best practice for the final image: **don't run a `RUN` that mutates a directory
|
||||
already populated by an earlier layer.** Each Dockerfile instruction is its own
|
||||
layer; if `/usr/local/bin/` is created by a `COPY` (containing the ~3 MB
|
||||
`tailscale.combined`) and a later `RUN ln -s …` adds a symlink *inside that same
|
||||
directory*, overlayfs performs a **copy-up** of the entire directory — including
|
||||
the 3 MB binary — into the new layer. The binary then physically exists in two
|
||||
image layers.
|
||||
|
||||
The fix: assemble `/usr/local/bin/` completely in the **builder** stage (binary
|
||||
+ both `argv[0]` symlinks) and bring it into the final image with a **single
|
||||
`COPY` layer**, never mutating it afterwards. The Dockerfile does this; don't
|
||||
reintroduce a post-`COPY` `RUN` against that path. You can confirm the published
|
||||
image carries the binary in exactly one layer:
|
||||
|
||||
```
|
||||
docker save <image> -o img.tar && tar xf img.tar -C img/
|
||||
# then grep each blob layer for usr/local/bin/tailscale.combined — it must
|
||||
# appear in exactly ONE layer.
|
||||
```
|
||||
|
||||
Note: this is about keeping the *image* clean. It does **not** change what `du`
|
||||
reports on the device — see the measurement note below.
|
||||
|
||||
To verify the on-flash footprint on a deployed router, use the **free-space
|
||||
delta**, not `du`:
|
||||
|
||||
```
|
||||
/system/resource/print # note free-hdd-space before and after adding the container
|
||||
```
|
||||
|
||||
The container should consume **~4.2 MiB** of flash (e.g. 94.6 → 90.4 MiB free).
|
||||
|
||||
Do **not** trust `du` inside the container for this. Busybox `du` reports
|
||||
*allocated blocks*, and RouterOS's container store rounds the ~3.5 MB binary up
|
||||
to ~7 MB of blocks — so `du -sx /` reports ~8 MB even though real flash use is
|
||||
~4.2 MB. `ls -la /usr/local/bin` confirms the binary's true content size
|
||||
(~3.5 MB) and that it is a single file with two symlinks (no duplication).
|
||||
The image itself carries the binary in exactly one layer (verified at the blob
|
||||
level); the inflation is purely the filesystem's block accounting.
|
||||
|
||||
## Architecture support
|
||||
|
||||
A single Dockerfile builds all three supported RouterOS architectures. The Go
|
||||
binary is **cross-compiled** (the builder stage runs natively on the host for
|
||||
speed), while the busybox stage and final image are built for the target
|
||||
platform (via `buildx` + QEMU/binfmt for non-native targets).
|
||||
|
||||
**ARMv5 is not supported** (hEX Refresh / hAP ax S, EN7562CT CPU — RouterOS
|
||||
calls these `arm32v5`). ARMv5 has no Alpine/musl base image, so it cannot use
|
||||
this image's musl + `scratch` design; it would require a glibc (Debian) base
|
||||
and produce a substantially larger image (~50 MB+ vs ~4 MB). If you need it,
|
||||
that's a separate build, not just a `--platform` change.
|
||||
|
||||
## Features included
|
||||
|
||||
| Feature | Why |
|
||||
|---|---|
|
||||
| `advertise-exit-node` | Run the router as a Tailscale exit node |
|
||||
| `advertise-routes` | Expose LAN subnets to the tailnet |
|
||||
| `use-exit-node` | Route the router's own traffic via a remote exit node |
|
||||
| `accept-routes` | Receive subnet routes from other tailnet nodes |
|
||||
| DNS / MagicDNS | Resolve `*.ts.net` names (resolver + resolv.conf manager). **Note:** serving `100.100.100.100` also requires `netstack` — see [Why netstack is required (even with a kernel TUN)](#why-netstack-is-required-even-with-a-kernel-tun) |
|
||||
| `netstack` + `gro` | gVisor userspace stack. Counter-intuitively **required** to serve MagicDNS on `100.100.100.100`, even though the router uses a real kernel TUN — see [Why netstack is required (even with a kernel TUN)](#why-netstack-is-required-even-with-a-kernel-tun) |
|
||||
| `peerapiserver` | Serves the PeerAPI, including the `/dns-query` DoH endpoint that lets **exit-node clients resolve public DNS automatically**. A declared dependency of `advertise-exit-node` that the allowlist didn't pull in — see [Why peerapiserver is required for exit-node DNS](#why-peerapiserver-is-required-for-exit-node-dns) |
|
||||
| udptransport | **Required** for direct peer connections (split out in v1.104.0). Without it magicsock never runs its UDP receive loops, all traffic is relayed via DERP, and health reports "The MagicSock function ReceiveIPv4 is not running" |
|
||||
| nattraversal | STUN, disco hole punching, UDP peer relay client (split out in v1.104.0). Without it direct UDP only works to peers with directly reachable endpoints |
|
||||
| portmapper (NAT-PMP/PCP/UPnP) | Punch through upstream NAT |
|
||||
| listenrawdisco | Raw socket disco for better NAT traversal |
|
||||
| health | Powers `tailscale status` output |
|
||||
| iptables | Linux iptables support for routing rules |
|
||||
| osrouter | Configure kernel network stack and routing tables |
|
||||
| unixsocketidentity | **Required** — without it the localapi denies every CLI call with "access denied" ([tailscale#17873](https://github.com/tailscale/tailscale/issues/17873)) |
|
||||
| ipnbus | Lets `tailscale up` wait for completion and print the login URL; without it `up` returns immediately without confirming success |
|
||||
|
||||
## Features intentionally omitted
|
||||
|
||||
| Feature | Reason |
|
||||
|---|---|
|
||||
| `clientupdate` | **Deliberately removed** — see [Why the built-in updater is removed](#why-the-built-in-updater-is-removed) |
|
||||
| `cachenetmap` | **Deliberately removed** — see [Why netmap disk-caching is removed](#why-netmap-disk-caching-is-removed) |
|
||||
| `logtail` | Would attempt persistent log writes; wear flash. Removing it also removes stderr verbosity filtering — restored by an injected filter, see [Log verbosity filtering](#log-verbosity-filtering) |
|
||||
| `netlog` | Network flow logging; separate concern |
|
||||
| `dnsresolvecache` | Persists DNS resolutions to disk — flash writes for a marginal cold-start benefit |
|
||||
| `ssh` | Access via MikroTik SSH + `tailscale` CLI instead |
|
||||
| `linuxdnsfight` | inotify on `/etc/resolv.conf`; no systemd in container |
|
||||
| `networkmanager` / `resolved` / `dbus` / `sdnotify` | No systemd stack in container |
|
||||
| `drive` / `taildrop` / `webclient` | Not useful on a headless router |
|
||||
| All GUI / desktop / cloud / k8s features | Irrelevant |
|
||||
|
||||
### Why the built-in updater is removed
|
||||
|
||||
Tailscale's `clientupdate` feature (and `tailscale update` / auto-update) is
|
||||
**intentionally compiled out**, for several compounding reasons:
|
||||
|
||||
- **It would defeat the entire purpose of this build.** `clientupdate`
|
||||
downloads the *full official upstream binary* — built with every feature, tens
|
||||
of megabytes — and writes it onto the device. This image exists precisely to
|
||||
be a few MB with only router-relevant features; letting it pull the upstream
|
||||
binary would undo all of that.
|
||||
- **It would risk filling the flash.** On a 16 MB-class device, downloading and
|
||||
unpacking a large upstream binary can simply run the device out of space, and
|
||||
the download itself causes significant flash writes.
|
||||
- **It can't work on a container image anyway.** The binary lives in a
|
||||
read-only, content-addressed image layer. An in-place self-update has nowhere
|
||||
valid to write and would not survive a container recreate — the next pull
|
||||
would replace it regardless.
|
||||
- **Updates should be controlled and reproducible.** Instead of the client
|
||||
silently swapping its own binary, new versions are produced by rebuilding and
|
||||
republishing *this* image through CI (pinned dependencies, known feature set,
|
||||
multi-arch). The device then pulls a new image **only when it actually
|
||||
changed** — see [Versioning & releases](#versioning--releases).
|
||||
|
||||
Net effect: the update path is explicit, version-pinned, flash-safe, and keeps
|
||||
the on-device footprint minimal — none of which the built-in updater could
|
||||
provide here.
|
||||
|
||||
### Why netmap disk-caching is removed
|
||||
|
||||
The `cachenetmap` feature is **intentionally omitted**. It is worth being
|
||||
precise about what it does and doesn't do:
|
||||
|
||||
- The network map always lives in the daemon's **memory** — this is core
|
||||
behavior, not gated by any feature flag. A daemon that has connected once and
|
||||
then **loses its control-plane connection keeps that map** and can still
|
||||
reach known peers. The data path is direct WireGuard / DERP between nodes; the
|
||||
control plane is only for coordination, not for relaying your traffic. So
|
||||
initiating a connection to a reachable peer during a control outage works
|
||||
**without** this feature, as long as the daemon stays running.
|
||||
- `cachenetmap` *only* adds writing that map to **disk**, so the node can come
|
||||
online from the last-known config after a **cold start that coincides with a
|
||||
control-plane outage** — a narrow case (it requires a reboot *and* control
|
||||
being unreachable at that moment *and* needing connectivity before control
|
||||
recovers).
|
||||
|
||||
The cost of the feature is that it writes the netmap to flash, and the netmap
|
||||
changes frequently on an active tailnet (every peer endpoint/DERP/online-status
|
||||
change). For a flash-constrained router that is the wrong trade: frequent writes
|
||||
to internal flash to buy resilience for a rare corner case. Omitting it keeps
|
||||
the in-memory resilience (the common case) while eliminating per-netmap flash
|
||||
writes. Only `tailscaled.state` (written on auth / key rotation) ever touches
|
||||
flash.
|
||||
|
||||
### Why netstack is required (even with a kernel TUN)
|
||||
|
||||
This is the least obvious inclusion in the build, so it is documented in full.
|
||||
|
||||
`netstack` is Tailscale's embedded **gVisor userspace TCP/IP stack**. The
|
||||
natural assumption — and what earlier versions of this build acted on — is that
|
||||
a router which owns a **real kernel TUN device** (it is *not* run with
|
||||
`--tun=userspace-networking`) has no use for a userspace stack, so `netstack`
|
||||
(and its dependent `gro`) can be omitted to save space. That assumption is
|
||||
**wrong for one specific, important path: MagicDNS.**
|
||||
|
||||
**MagicDNS on `100.100.100.100` is served only by netstack.** In Tailscale
|
||||
v1.98.5 the in-process listener for the Tailscale service IP
|
||||
(`100.100.100.100:53`, UDP) is installed exclusively by netstack's
|
||||
`handleLocalPackets`, wired into the TUN wrapper as
|
||||
`PreFilterPacketOutboundToWireGuardNetstackIntercept`
|
||||
(`wgengine/netstack/netstack.go`). When a packet leaves the host toward
|
||||
`100.100.100.100`, this hook absorbs it into the gVisor stack, whose UDP-53
|
||||
acceptor runs the MagicDNS resolver.
|
||||
|
||||
**The "engine fallback" does not actually exist.** The TUN wrapper consults a
|
||||
second hook, `PreFilterPacketOutboundToWireGuardEngineIntercept`, and a comment
|
||||
in `net/tstun/wrap.go` claims it "primarily handles quad-100 if netstack is not
|
||||
installed." In v1.98.5 that comment is **false on Linux**: the engine
|
||||
`handleLocalPackets` (`wgengine/userspace.go`) only reflects loopback on
|
||||
darwin/ios/plan9 and otherwise returns `Accept` — it never touches
|
||||
`100.100.100.100`. So with `ts_omit_netstack` there is **no** code that absorbs
|
||||
quad-100 packets at all.
|
||||
|
||||
**`dns` and `netstack` are independent tags.** The `dns` feature (which this
|
||||
build opts in) links the resolver and the `/etc/resolv.conf` manager, but it has
|
||||
no dependency on `netstack` and does **not** install any quad-100 transport.
|
||||
The net result of `dns` on + `netstack` off is a resolver that is correctly
|
||||
wired up but that **never receives any packets** — the worst kind of silent
|
||||
breakage. Symptoms observed on the device:
|
||||
|
||||
- `/etc/resolv.conf` correctly points at `100.100.100.100` (the manager works),
|
||||
- but `dig anything @100.100.100.100` from inside the container **times out**
|
||||
("no servers could be reached"),
|
||||
- and even tailnet-internal names fail: `ping host.<tailnet>.ts.net` →
|
||||
`bad address` (a name that needs **no** upstream forwarding still can't
|
||||
resolve, proving the listener itself is dead, not an upstream-resolver issue),
|
||||
- while `ping 1.1.1.1` (a raw IP needing no DNS) works fine over the kernel data
|
||||
path — confirming forwarding/exit-node connectivity is unaffected and isolating
|
||||
the fault to DNS serving.
|
||||
|
||||
**It also fixed a crash.** Omitting `netstack` set `buildfeatures.HasNetstack`
|
||||
to a compile-time `false`, which turned the guard in
|
||||
`net/tstun.invertGSOChecksum` (`if !HasNetstack { panic("unreachable") }`) into
|
||||
an always-panic. That function is called on the packet-injection path used when
|
||||
enabling exit-node mode, producing `panic: unreachable` and a daemon restart
|
||||
loop. Enabling `netstack` makes `HasNetstack` a const `true`, so the guard
|
||||
becomes dead code and the crash disappears as a side effect — fixed at the root
|
||||
cause rather than patched around.
|
||||
|
||||
**Cost.** Measured on arm64, a netstack-enabled build versus a netstack-omitted
|
||||
one:
|
||||
|
||||
| Metric | netstack omitted | netstack enabled | Delta |
|
||||
|---|---|---|---|
|
||||
| Extracted rootfs (flash) | ~3.42 MB | ~3.91 MB | **+0.49 MB** |
|
||||
| `tailscale.combined` on disk (UPX) | ~2.99 MB | ~3.47 MB | +0.48 MB |
|
||||
| Resident RAM after UPX decompress | ~12.25 MB | ~14.56 MB | **+2.31 MB** |
|
||||
|
||||
The flash cost (~0.5 MB) is negligible on a 16 MB-class device. The RAM cost
|
||||
(~2.3 MB resident) is the real consideration on low-memory models, but is
|
||||
acceptable given that without it MagicDNS is entirely non-functional. The
|
||||
trade is: **half a megabyte of flash to make MagicDNS work at all.** `gro`
|
||||
(Generic Receive Offload) depends on `netstack` and is pulled in alongside it;
|
||||
it is small and improves throughput on the netstack path.
|
||||
|
||||
**Caveat for future Tailscale bumps.** This coupling (quad-100 serving living
|
||||
only in netstack) is an upstream implementation detail, not a stable contract.
|
||||
If a future release adds a genuine non-netstack quad-100 path — or the daemon
|
||||
itself is refactored — re-test whether `netstack` can be dropped again. The
|
||||
canary is simple: from inside the container, `dig google.com @100.100.100.100`
|
||||
must return answers and `ping <host>.<tailnet>.ts.net` must resolve.
|
||||
|
||||
### Why peerapiserver is required for exit-node DNS
|
||||
|
||||
This is a second non-obvious DNS inclusion, and it exposes a limitation of the
|
||||
allowlist build strategy.
|
||||
|
||||
**Symptom.** With `netstack` enabled, MagicDNS worked from the router and from
|
||||
LAN hosts, including public names. But a device using this router **as its exit
|
||||
node** could not resolve public names: `dig google.com @100.100.100.100` on the
|
||||
*client* returned an instant authoritative `SERVFAIL` (`flags: qr aa rd ad`,
|
||||
`Query time: 0 msec`, "recursion not available"). Tailnet names and raw-IP
|
||||
connectivity (e.g. `ping 1.1.1.1`) through the exit node worked.
|
||||
|
||||
**Root cause.** The `SERVFAIL` is generated **on the client**, locally, with no
|
||||
network I/O — which is why it is instant and authoritative. The path
|
||||
(traced through v1.98.5 source):
|
||||
|
||||
1. The client's query for `google.com` reaches its in-process resolver, which
|
||||
determines the name is not a tailnet name and marks it for forwarding
|
||||
(`net/dns/resolver/tsdns.go`).
|
||||
2. The forwarder looks up which upstream resolver to use for the catch-all
|
||||
`"."` route (`net/dns/resolver/forwarder.go` → `resolvers()`).
|
||||
3. That route set is **empty**, so `forwardWithDestChan` short-circuits and
|
||||
synthesises an authoritative `SERVFAIL` (`servfailResponse`, `aa=1`) without
|
||||
opening any socket. The query never reaches this router at all.
|
||||
|
||||
Why the route set is empty: when a client selects an exit node,
|
||||
`dnsConfigForNetmap` (`ipn/ipnlocal/node_backend.go`) deliberately routes **all**
|
||||
default DNS through the exit node and drops the client's own LAN/system
|
||||
resolver — the whole premise of an exit node is "send everything, including
|
||||
DNS, through me." It does this by setting the client's default resolver to the
|
||||
exit node's **DoH proxy** URL (`http://<peer>/dns-query`). But that only happens
|
||||
if `exitNodeCanProxyDNS(thisRouter)` returns true — i.e. if **this router
|
||||
advertises a working PeerAPI DoH endpoint**. If it does not, and there is no
|
||||
tailnet global nameserver to fall back to, the client ends up with an empty
|
||||
default route and returns `SERVFAIL`.
|
||||
|
||||
**Why this router didn't advertise the DoH proxy.** The `/dns-query` DoH
|
||||
endpoint is part of the **PeerAPI server**, gated by
|
||||
`buildfeatures.HasPeerAPIServer` (`ipn/ipnlocal/peerapi.go`). With
|
||||
`ts_omit_peerapiserver`, `initPeerAPIListenerLocked()` returns early: no PeerAPI
|
||||
listener is created, the `PeerAPIDNS` service is never advertised, and
|
||||
`peerCanProxyDNS()` is false for this node on every client.
|
||||
|
||||
**The allowlist gap that caused it.** In `feature/featuretags/featuretags.go`,
|
||||
`advertiseexitnode` **declares a dependency on `peerapiserver`** ("to run the
|
||||
ExitDNS server"). Upstream's own `--add` resolution would have pulled it in.
|
||||
But this build's allowlist works differently: it runs `featuretags --min` to get
|
||||
the full omit set, then strips the specific `ts_omit_<feature>` tags it wants —
|
||||
it does **not** re-resolve transitive `Deps`. So opting in `advertiseexitnode`
|
||||
did not pull in `peerapiserver`, and `featuretags --min` had emitted
|
||||
`ts_omit_peerapiserver`, leaving the node an exit node *without* its declared
|
||||
ExitDNS dependency — a feature combination upstream's graph says shouldn't
|
||||
occur. Including `peerapiserver` explicitly closes the gap.
|
||||
|
||||
> **Known limitation:** the allowlist (strip-individual-`ts_omit_`-tags) does
|
||||
> not resolve feature dependencies. When opting a feature in, check its `Deps`
|
||||
> in `featuretags.go` and add them explicitly. `peerapiserver` is the only such
|
||||
> gap found and fixed so far; a full dependency audit has not been done.
|
||||
|
||||
**Cost.** Negligible. `peerapiserver` has **no** `Deps` and pulls in no large
|
||||
subsystems; measured at ~+10 kB on the UPX'd binary (arm64), rootfs unchanged
|
||||
within measurement noise.
|
||||
|
||||
**Result.** The router now serves the exit-node DoH DNS proxy, so devices using
|
||||
it as their exit node resolve public names automatically — the normal exit-node
|
||||
behavior — with **no** tailnet DNS configuration required. (Setting a tailnet
|
||||
global nameserver in the admin console is an alternative runtime fix that also
|
||||
works, by populating the client's default resolver directly; it is not required
|
||||
once the router serves the proxy.)
|
||||
|
||||
**Canary for future bumps:** from a client using this router as exit node,
|
||||
`dig google.com @100.100.100.100` must return real answers with `flags: ... ra`
|
||||
(recursion available) and a non-zero query time.
|
||||
|
||||
### Log verbosity filtering
|
||||
|
||||
Upstream `tailscaled` embeds verbosity tags (`[v1]`, `[v2]`, …) inside its log
|
||||
messages and relies on the **logtail** subsystem to act on them: in a stock
|
||||
build, logtail's log policy intercepts everything written via the standard
|
||||
`log` package, parses the tag, and only writes a line to stderr when its level
|
||||
is within `--verbose` (default 0 — non-verbose messages only). The `--verbose`
|
||||
flag is literally wired into logtail (`pol.SetVerbosityLevel(args.verbose)` in
|
||||
`cmd/tailscaled/tailscaled.go`).
|
||||
|
||||
This build omits logtail (`ts_omit_logtail`) to avoid log-upload code and
|
||||
flash writes — but that removed the stderr filtering along with it, as
|
||||
collateral damage. The result: every verbose line went **unfiltered** to
|
||||
stderr and into the RouterOS container log, with the literal `[v1]` tag still
|
||||
in the text. On an active node that means constant spam, several lines per
|
||||
minute:
|
||||
|
||||
```
|
||||
tailscale: ... [v1] Accept: TCP{...:53256 > ...:50000} 391 tcp non-syn
|
||||
tailscale: ... netcheck: [v1] report: udp=true v6=true ... derp=22 ...
|
||||
tailscale: ... wg: [v2] [0GwzF] - Receiving keepalive packet
|
||||
```
|
||||
|
||||
This is a [known](https://github.com/tailscale/tailscale/issues/12158)
|
||||
[long-standing](https://github.com/tailscale/tailscale/issues/1548) complaint
|
||||
even in full builds, and RouterOS logging offers no way to discard matching
|
||||
messages (no drop action, rules are all-match — a regex rule duplicates rather
|
||||
than diverts).
|
||||
|
||||
The fix here: the build injects a ~20-line Go file
|
||||
(`patches/stderr_verbosity_filter.go`, copied into `cmd/tailscaled/` before
|
||||
`go build`) whose `init()` wraps the standard log output and silently drops
|
||||
any line carrying a `[v1]`/`[v2]`/`[v3]` tag. This restores the exact
|
||||
equivalent of logtail's default `StderrLevel=0` behavior without pulling in
|
||||
the upload machinery. Properties:
|
||||
|
||||
- **No upstream sources modified** — it's a new file in the package, so it
|
||||
survives Tailscale version bumps without rebasing (only relies on the
|
||||
daemon using the stdlib `log` package, which is core behavior).
|
||||
- **Build-tagged `//go:build ts_omit_logtail`** — if logtail is ever
|
||||
re-enabled, the file compiles out automatically and logtail's own filtering
|
||||
takes over; the two can never conflict.
|
||||
- **Runtime escape hatch** — setting the `TS_LOG_VERBOSITY=1` environment
|
||||
variable disables the filter (and, conveniently, the same knob is read by
|
||||
upstream as the default `--verbose` level). Verbose logs are one
|
||||
`/container/envs/add` away; no rebuild needed. See
|
||||
[USAGE.md → Logging](USAGE.md#logging).
|
||||
|
||||
## Volume layout
|
||||
|
||||
Two mount points, with different persistence requirements:
|
||||
|
||||
```
|
||||
/var/lib/tailscale persistent — node identity, auth state
|
||||
bind-mount to MikroTik disk storage
|
||||
written rarely (only on auth / key rotation /
|
||||
prefs change); netmap is not cached to disk
|
||||
(cachenetmap omitted), so no per-netmap writes
|
||||
|
||||
/var/run/tailscale ephemeral — daemon Unix socket
|
||||
mount as tmpfs
|
||||
lost on reboot, recreated on start
|
||||
```
|
||||
|
||||
Only the small, rarely-written state file touches flash; the socket dir is
|
||||
tmpfs. The netmap is held in memory only — see
|
||||
[Why netmap disk-caching is removed](#why-netmap-disk-caching-is-removed).
|
||||
|
||||
### What lives in the state dir
|
||||
|
||||
| File | Purpose | Write frequency |
|
||||
|---|---|---|
|
||||
| `tailscaled.state` | Node identity, auth keys, prefs | On auth / key rotation / prefs change |
|
||||
| `derpmap.cached.json` | Cached DERP relay server list for **bootstrap DNS**: at cold start with broken/unavailable DNS, tailscaled asks DERP servers to resolve the control plane. The binary ships a static DERP list, but it goes stale; this cache keeps the current one. | Once at first auth, then **only when Tailscale's relay infrastructure changes** (a few times a year). `dnsfallback.UpdateCache` has a deep-equal guard and skips the write when the DERP map is unchanged — netmap churn never touches it. |
|
||||
|
||||
`derpmap.cached.json` is intentionally **kept** despite the flash-wear policy:
|
||||
the policy targets *frequent* writes (netmap deltas, logs), not one-shot
|
||||
caches. On a router this cache is genuinely useful — after a power outage the
|
||||
device may boot with WAN up but upstream DNS broken, exactly the case where a
|
||||
fresh DERP list lets the node reach the control plane anyway. With
|
||||
`cachenetmap` omitted, this file and `tailscaled.state` are the only cold-start
|
||||
resilience the node has. (There is no `ts_omit_*` tag for it; it is written
|
||||
only because `--statedir` is set.)
|
||||
|
||||
## Flash wear protection
|
||||
|
||||
Several measures are in place to avoid wearing out internal flash:
|
||||
|
||||
- `clientupdate` omitted from binary — no background update downloads
|
||||
([why](#why-the-built-in-updater-is-removed))
|
||||
- `cachenetmap` omitted from binary — netmap is never written to disk, so the
|
||||
frequent netmap updates cause no flash writes
|
||||
([why](#why-netmap-disk-caching-is-removed))
|
||||
- `logtail` omitted from binary — no log upload attempts
|
||||
- `--no-logs-no-support` passed to daemon — suppresses any remaining log
|
||||
buffering
|
||||
- `/var/run/tailscale` socket on tmpfs — runtime files never reach flash
|
||||
- Only `/var/lib/tailscale/tailscaled.state` touches persistent storage,
|
||||
and it is written only when the node authenticates or rotates its key
|
||||
|
||||
## Versioning & releases
|
||||
|
||||
Released images are versioned as:
|
||||
|
||||
```
|
||||
v<TAILSCALE_VERSION>-mt.<N>
|
||||
```
|
||||
|
||||
e.g. `v1.98.3-mt.1`. The two parts mean:
|
||||
|
||||
- **`v<TAILSCALE_VERSION>`** — the bundled Tailscale version (the "what's
|
||||
inside" identifier), taken from `ARG TAILSCALE_VERSION` in the Dockerfile.
|
||||
- **`mt.<N>`** — the local revision. It only changes on a *meaningful* release,
|
||||
never on a build-system-only rebuild.
|
||||
|
||||
### When a release happens
|
||||
|
||||
| Trigger | Result |
|
||||
|---|---|
|
||||
| Renovate bumps `TAILSCALE_VERSION` (merged to `main`) | CI **auto-creates** git tag `v<new>-mt.1` → image published |
|
||||
| You make a meaningful fix/change on the current Tailscale version | **You** create the next tag manually (`v<ts>-mt.2`, `mt.3`, …) → image published |
|
||||
| Dependency-only bump (Go / Alpine / busybox / Dockerfile syntax) | **No release.** Rides along with the next Tailscale bump or manual tag |
|
||||
|
||||
So routers only ever see a new release for Tailscale bumps or your deliberate
|
||||
fixes — build-system churn doesn't trigger updates.
|
||||
|
||||
Each published image is stamped with `org.opencontainers.image.version` equal to
|
||||
its full tag; this is the value the MikroTik update job compares against the
|
||||
registry to decide whether to recreate the container.
|
||||
|
||||
### How it's wired (Woodpecker)
|
||||
|
||||
- **`.woodpecker/release-tag.yaml`** — on push to `main`, parses
|
||||
`TAILSCALE_VERSION`; if no `v<ts>-mt.*` tag exists yet, creates and pushes
|
||||
`v<ts>-mt.1` (using the Gitea token from OpenBao). It never creates `mt.2+`.
|
||||
- **`.woodpecker/release.yaml`** — on a `v*-mt.*` tag push, builds the
|
||||
multi-arch manifest (amd64 + arm64 + arm/v7) and pushes it to
|
||||
`gitea.lumpiasty.xyz/lumpiasty/mikrotik-tailscale` as both `:<tag>` and
|
||||
`:stable`. Registry creds come from OpenBao (`secret/container-registry`).
|
||||
|
||||
To cut a release manually, see
|
||||
[DEVELOPMENT.md → Cutting a manual release](DEVELOPMENT.md#cutting-a-manual-release).
|
||||
|
||||
### How the router consumes releases
|
||||
|
||||
The RouterOS update script (`routeros/update-tailscale.rsc`) compares the
|
||||
`:stable` **manifest digest** against the digest from the last deploy:
|
||||
|
||||
- It fetches the digest using an anonymous bearer token (the Gitea package is
|
||||
public) — no credentials stored on the router.
|
||||
- **Unchanged → does nothing** (no pull, no recreate, no flash wear).
|
||||
- **Changed → recreates the container** from the new image, then records the
|
||||
new digest.
|
||||
|
||||
Because `:stable` only moves on a meaningful release, dependency-only rebuilds
|
||||
never trigger an update on the router. Setup is in
|
||||
[USAGE.md → step 7](USAGE.md#7-enable-automatic-updates).
|
||||
|
||||
## Dependency pinning & automated updates
|
||||
|
||||
All upstream dependencies are version-pinned for reproducible builds, fully
|
||||
qualified (no floating `major.minor` tags):
|
||||
|
||||
| Dependency | Where | Pinned form |
|
||||
|---|---|---|
|
||||
| Go toolchain | `Dockerfile` `FROM golang:…` | full version tag + `@sha256` digest |
|
||||
| Alpine (busybox build base) | `Dockerfile` `FROM alpine:…` | full version tag + `@sha256` digest |
|
||||
| Tailscale | `Dockerfile` `ARG TAILSCALE_VERSION` | full git release tag |
|
||||
| busybox | `Dockerfile` `ARG BUSYBOX_VERSION` | full release version |
|
||||
| Renovate / OpenBao | `.woodpecker/*.yaml` `image:` | full version tag |
|
||||
|
||||
Updates are proposed automatically by [Renovate](https://docs.renovatebot.com/),
|
||||
run **self-hosted** from a Woodpecker cron pipeline (Woodpecker has no native
|
||||
Renovate support):
|
||||
|
||||
- `renovate.json` — repository rules. All dependencies follow the latest
|
||||
upstream releases; each bump arrives as its own PR. Base image tags also get
|
||||
their `@sha256` digests refreshed via `pinDigests`. Notable rules:
|
||||
- `tailscale` only follows **stable** releases — Tailscale uses even minor
|
||||
versions for stable (`v1.98.x`) and odd for unstable (`v1.99.x`), so the
|
||||
rule filters to even minors.
|
||||
- `.woodpecker/renovate.yaml` — the scheduled job that runs `renovate/renovate`
|
||||
against this repo.
|
||||
- `.woodpecker/pr-build.yaml` — builds all three arches (no push) on every PR
|
||||
and reports status to Gitea. This is the gate for automerge.
|
||||
|
||||
### Automerge policy
|
||||
|
||||
These updates **automerge** once the PR build passes — they reach `:stable`
|
||||
(and the routers) without manual review:
|
||||
|
||||
| Update | Automerge? | Why |
|
||||
|---|---|---|
|
||||
| Tailscale stable (patch **and** minor) | ✅ | the point of the project; the PR build catches breakage |
|
||||
| Go / Alpine / busybox **patch** | ✅ | bugfix-only, build-internal |
|
||||
| Base-image **digest** refresh (same tag) | ✅ | content refresh, no version change |
|
||||
| Go / Alpine / busybox **minor/major** | ❌ manual | larger toolchain/base changes warrant review |
|
||||
| Renovate runner, syntax frontend | ❌ manual | tooling — review deliberately |
|
||||
|
||||
**Important:** automerge depends on the PR build being a **required status
|
||||
check** in Gitea branch protection. The PR build only proves the image *builds*
|
||||
for all arches — it does not run the daemon, so a runtime regression in a new
|
||||
Tailscale release could still be automerged. That is an accepted trade-off for
|
||||
the convenience of unattended Tailscale updates; if a release misbehaves, roll
|
||||
back by re-tagging the previous `v…-mt.N` (the immutable tags are kept).
|
||||
|
||||
Validate the configs locally:
|
||||
|
||||
```sh
|
||||
# Renovate repo config
|
||||
docker run --rm -e RENOVATE_CONFIG_TYPE=repo -v "$PWD":/work -w /work \
|
||||
--entrypoint renovate-config-validator renovate/renovate
|
||||
|
||||
# Woodpecker pipeline
|
||||
docker run --rm -v "$PWD":/work -w /work \
|
||||
woodpeckerci/woodpecker-cli:v3 lint .woodpecker/renovate.yaml
|
||||
```
|
||||
|
||||
## References
|
||||
|
||||
- [Tailscale: Smaller binaries for embedded devices](https://tailscale.com/docs/how-to/set-up-small-tailscale)
|
||||
- [Renovate self-hosting](https://docs.renovatebot.com/getting-started/running/)
|
||||
- [Woodpecker cron jobs](https://woodpecker-ci.org/docs/usage/cron)
|
||||
- [MikroTik Container documentation](https://help.mikrotik.com/docs/display/ROS/Container)
|
||||
- [Tailscale subnet routers](https://tailscale.com/kb/1019/subnets)
|
||||
- [Tailscale exit nodes](https://tailscale.com/kb/1103/exit-nodes)
|
||||
@@ -0,0 +1,159 @@
|
||||
# Development
|
||||
|
||||
Building the image, testing it locally, bumping the Tailscale version, and
|
||||
cutting releases. This is for working *on* this repo; if you just want to run
|
||||
the published image on a router, see [USAGE.md](USAGE.md).
|
||||
|
||||
For the reasoning behind the build choices, see [DESIGN.md](DESIGN.md).
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- `docker` with `buildx`.
|
||||
- For cross-arch builds, QEMU/binfmt emulators registered:
|
||||
|
||||
```sh
|
||||
docker run --privileged --rm tonistiigi/binfmt --install arm64,arm
|
||||
```
|
||||
|
||||
The Go toolchain and busybox are built inside the image stages, so no local Go
|
||||
install is needed.
|
||||
|
||||
## Building
|
||||
|
||||
### All architectures at once
|
||||
|
||||
Use the helper script:
|
||||
|
||||
```sh
|
||||
# Build all arches and load into local docker
|
||||
./build.sh
|
||||
|
||||
# Build all arches and also export per-arch tarballs into ./dist/
|
||||
./build.sh --tar
|
||||
|
||||
# Build a single arch
|
||||
./build.sh arm64
|
||||
./build.sh --tar armv7
|
||||
```
|
||||
|
||||
### Manual single-arch build
|
||||
|
||||
The architecture is selected via `buildx --platform`; the Dockerfile maps it to
|
||||
the correct `GOARCH`/`GOARM` automatically:
|
||||
|
||||
```sh
|
||||
docker buildx build --platform linux/arm64 --load -t mikrotik-tailscale:arm64 .
|
||||
docker buildx build --platform linux/arm/v7 --load -t mikrotik-tailscale:armv7 .
|
||||
docker buildx build --platform linux/amd64 --load -t mikrotik-tailscale:amd64 .
|
||||
```
|
||||
|
||||
To build for a different Tailscale version, add:
|
||||
|
||||
```sh
|
||||
--build-arg TAILSCALE_VERSION=v1.98.3
|
||||
```
|
||||
|
||||
### Notes
|
||||
|
||||
- The Go builder cross-compiles natively (fast); only the busybox stage runs
|
||||
under emulation for non-native targets.
|
||||
- The build prints the resolved target and Go build tags, e.g.:
|
||||
|
||||
```
|
||||
Cross-compiling: GOOS=linux GOARCH=arm64 GOARM=
|
||||
Build tags: ts_include_cli,ts_omit_ace,ts_omit_acme,...
|
||||
```
|
||||
|
||||
## Running (local test)
|
||||
|
||||
Quick smoke test on a dev machine with Docker (this is *not* how it runs on a
|
||||
router — see [USAGE.md](USAGE.md) for that):
|
||||
|
||||
```sh
|
||||
# Create a volume for persistent state
|
||||
docker volume create tailscale-state
|
||||
|
||||
# Start the daemon
|
||||
docker run -d \
|
||||
--name tailscale \
|
||||
--cap-add NET_ADMIN \
|
||||
--cap-add NET_RAW \
|
||||
--device /dev/net/tun \
|
||||
--tmpfs /var/run/tailscale \
|
||||
-v tailscale-state:/var/lib/tailscale \
|
||||
mikrotik-tailscale
|
||||
|
||||
# Authenticate (opens browser / prints auth URL)
|
||||
docker exec tailscale tailscale login
|
||||
|
||||
# Check status
|
||||
docker exec tailscale tailscale status
|
||||
|
||||
# Advertise a subnet
|
||||
docker exec tailscale tailscale set --advertise-routes=192.168.88.0/24
|
||||
|
||||
# Advertise as exit node
|
||||
docker exec tailscale tailscale set --advertise-exit-node
|
||||
```
|
||||
|
||||
Subnet routes and exit node advertisement must also be approved in the
|
||||
[Tailscale admin console](https://login.tailscale.com/admin/machines).
|
||||
|
||||
For headless / unattended auth, use a reusable auth key from the admin console
|
||||
(**Settings → Keys**):
|
||||
|
||||
```sh
|
||||
docker exec tailscale tailscale up \
|
||||
--authkey=tskey-auth-<key> \
|
||||
--advertise-routes=192.168.88.0/24 \
|
||||
--advertise-exit-node
|
||||
```
|
||||
|
||||
## Bumping the Tailscale version
|
||||
|
||||
Version bumps (Tailscale, busybox, base image digests) are normally proposed
|
||||
automatically via Renovate (see
|
||||
[DESIGN.md → Dependency pinning](DESIGN.md#dependency-pinning--automated-updates)).
|
||||
Merge the Renovate PR; a Tailscale bump then auto-publishes a new release.
|
||||
|
||||
The feature allowlist in the Dockerfile carries forward automatically across
|
||||
Tailscale versions — any new `ts_omit_*` tags introduced in a new release will
|
||||
be omitted by default.
|
||||
|
||||
To bump manually, edit `ARG TAILSCALE_VERSION` in the `Dockerfile` (so the pin
|
||||
stays in version control) and rebuild:
|
||||
|
||||
```sh
|
||||
./build.sh --tar # rebuild all arches at the pinned version
|
||||
# or, override at build time without editing the Dockerfile:
|
||||
docker buildx build --platform linux/arm64 \
|
||||
--build-arg TAILSCALE_VERSION=v1.100.0 \
|
||||
--load -t mikrotik-tailscale:arm64 .
|
||||
```
|
||||
|
||||
## Cutting a manual release
|
||||
|
||||
A Tailscale bump auto-creates `v<ts>-mt.1` and publishes it. For a meaningful
|
||||
fix/change on the *current* Tailscale version, tag the next `mt.N` by hand:
|
||||
|
||||
```sh
|
||||
# fix something, commit to main, then:
|
||||
git tag -a v1.98.3-mt.2 -m "Fix X"
|
||||
git push origin v1.98.3-mt.2
|
||||
```
|
||||
|
||||
The tag push triggers the build + multi-arch publish automatically. See
|
||||
[DESIGN.md → Versioning & releases](DESIGN.md#versioning--releases) for the full
|
||||
scheme and CI wiring.
|
||||
|
||||
## Validating CI configs locally
|
||||
|
||||
```sh
|
||||
# Renovate repo config
|
||||
docker run --rm -e RENOVATE_CONFIG_TYPE=repo -v "$PWD":/work -w /work \
|
||||
--entrypoint renovate-config-validator renovate/renovate
|
||||
|
||||
# Woodpecker pipelines
|
||||
docker run --rm -v "$PWD":/work -w /work \
|
||||
woodpeckerci/woodpecker-cli:v3 lint .woodpecker/renovate.yaml
|
||||
```
|
||||
+233
@@ -0,0 +1,233 @@
|
||||
# Usage
|
||||
|
||||
Deploying the published image on a MikroTik router and operating it: networking,
|
||||
authentication, MagicDNS, and automatic updates. This uses the prebuilt image
|
||||
from the registry — you don't need to build anything.
|
||||
|
||||
To build the image yourself, see [DEVELOPMENT.md](DEVELOPMENT.md). For the
|
||||
reasoning behind these choices, see [DESIGN.md](DESIGN.md).
|
||||
|
||||
## Deploy on MikroTik (RouterOS)
|
||||
|
||||
Verified on RouterOS 7.23 (arm64, CRS418). Commands are grouped into
|
||||
copy-paste blocks, defaults should fit most configurations.
|
||||
|
||||
> Because the image has no built-in updater (the `clientupdate` feature is
|
||||
> [intentionally compiled out](DESIGN.md#why-the-built-in-updater-is-removed)),
|
||||
> updates are handled by a small script that recreates container when
|
||||
> the update is published — see [step 7](#7-enable-automatic-updates).
|
||||
|
||||
### 0. Prerequisites
|
||||
|
||||
- RouterOS >= 7.23 with the **container** package installed
|
||||
(7.23 is needed for container `restart-policy`; the deploy itself works on
|
||||
>= 7.13 if you drop the restart options).
|
||||
- Container mode enabled ([documentation](https://manual.mikrotik.com/docs/System%20Information%20and%20Utilities/device-mode/#changing-mode-of-device-mode)):
|
||||
|
||||
```
|
||||
/system/device-mode/update container=yes
|
||||
```
|
||||
|
||||
### 1. Networking (veth + routing)
|
||||
|
||||
Gives the container an internal IP and configures routing to the tailnet.
|
||||
Pick a subnet that doesn't clash with your LAN.
|
||||
|
||||
```
|
||||
/interface/veth/add name=veth-tailscale address=172.20.0.2/24 gateway=172.20.0.1
|
||||
/interface/bridge/add name=containers
|
||||
/ip/address/add address=172.20.0.1/24 interface=containers
|
||||
/interface/bridge/port/add bridge=containers interface=veth-tailscale
|
||||
/ip/route/add dst-address=100.64.0.0/10 gateway=172.20.0.2 comment=Tailnet
|
||||
```
|
||||
|
||||
If you want the router to have access to subnets shared by other tailscale nodes,
|
||||
add route for each one.
|
||||
|
||||
```
|
||||
/ip/route/add dst-address=[subnet CIDR] gateway=172.20.0.2 comment="Another network via tailscale"
|
||||
```
|
||||
|
||||
If you want to share your LAN via tailscale, add it as an advertised route in
|
||||
[step 5](#5-authenticate). You may also need additional firewall configuration
|
||||
to accept connections to or from tailnet if you have one configured.
|
||||
You should not need any additional NAT rules.
|
||||
|
||||
### 2. Extraction scratch dir (tmpfs)
|
||||
|
||||
Put the image extraction scratch dir on **tmpfs** (RAM) so the pull/extract
|
||||
happen in RAM and doesn't fill up or wear out flash:
|
||||
|
||||
```
|
||||
/disk/add type=tmpfs tmpfs-max-size=256M slot=tmp
|
||||
/container/config/set tmpdir=tmp
|
||||
```
|
||||
|
||||
### 3. Persistent state mount (the only thing on flash)
|
||||
|
||||
Only the tiny `tailscaled.state` (node identity / key) needs to persist. Mount
|
||||
just that directory:
|
||||
|
||||
```
|
||||
/container/mounts/add list=tailscale_state src=tailscale/state dst=/var/lib/tailscale
|
||||
```
|
||||
|
||||
### 4. Add and start the container
|
||||
|
||||
```
|
||||
/container/add \
|
||||
remote-image=gitea.lumpiasty.xyz/lumpiasty/mikrotik-tailscale:stable \
|
||||
interface=veth-tailscale \
|
||||
root-dir=tailscale/root \
|
||||
mountlists=tailscale_state \
|
||||
logging=yes \
|
||||
start-on-boot=yes \
|
||||
restart-policy=on-failure \
|
||||
restart-interval=10s \
|
||||
name=tailscale
|
||||
```
|
||||
|
||||
Wait for the pull/extract to finish (`status=stopped`), then start it:
|
||||
|
||||
```
|
||||
/container/print ;# wait until status=stopped
|
||||
/container/start [find where name=tailscale]
|
||||
/log/print where message~"tailscale"
|
||||
```
|
||||
|
||||
The daemon is now running but **not yet authenticated**.
|
||||
|
||||
### 5. Authenticate
|
||||
|
||||
> This image runs `tailscaled` via a tiny entrypoint (which enables IP
|
||||
forwarding, then `exec`s the daemon) and does **not** bundle Tailscale's
|
||||
`containerboot` wrapper, so the `TS_AUTHKEY` environment variable is **not**
|
||||
read automatically. You authenticate with `tailscale up --authkey=...` after the
|
||||
container starts.
|
||||
|
||||
Enter the container shell and bring Tailscale up with your auth key.
|
||||
Use `tailscale up --help` to see list of commands, customize it to your needs,
|
||||
add subnets (eg. your LAN) or exit-node advertisements in command below.
|
||||
|
||||
```
|
||||
/container/shell [find where name=tailscale]
|
||||
# inside the container — CHANGE ME: your key (and adjust routes/subnet):
|
||||
tailscale up --authkey=tskey-auth-CHANGEME \
|
||||
--accept-routes \
|
||||
--snat-subnet-routes=false \
|
||||
--advertise-routes=172.20.0.0/24 \
|
||||
--advertise-exit-node
|
||||
exit
|
||||
```
|
||||
|
||||
The node now appears in your Tailscale admin console. Approve the advertised
|
||||
routes / exit node there. Because the auth state is written to the persisted
|
||||
`tailscaled.state`, you only do this once — it survives reboots and updates.
|
||||
|
||||
### 6. Enable automatic updates
|
||||
|
||||
First, edit the `CONFIG` block at the top of `routeros/update-tailscale.rsc` if
|
||||
you changed any names in the steps above. The defaults match this guide
|
||||
(`name=tailscale`, `root-dir=tailscale/root`, `mountlists=tailscale_state`,
|
||||
`interface=veth-tailscale`).
|
||||
|
||||
Copy the file to the router (Winbox **Files** drag-and-drop, or SFTP), then
|
||||
create a **named script** from it and schedule it:
|
||||
|
||||
```
|
||||
# Create the named script from the uploaded file's contents.
|
||||
/system/script/add name=update-tailscale source=[/file/get update-tailscale.rsc contents]
|
||||
|
||||
# Run it daily.
|
||||
/system/scheduler/add name=update-tailscale interval=1d \
|
||||
on-event="/system/script/run update-tailscale" \
|
||||
comment="Check for mikrotik-tailscale image updates"
|
||||
```
|
||||
|
||||
If you later upload a changed version of the file, refresh the script:
|
||||
|
||||
```
|
||||
/system/script/set update-tailscale source=[/file/get update-tailscale.rsc contents]
|
||||
```
|
||||
|
||||
What it does on each run:
|
||||
|
||||
1. Reads the current `:stable` manifest digest from the registry (anonymous —
|
||||
the package is public).
|
||||
2. Compares it to the digest stored from the last deploy.
|
||||
3. **Unchanged → does nothing** (no pull, no flash writes).
|
||||
4. **Changed → recreates the container** from the new image and records the new
|
||||
digest.
|
||||
|
||||
Since `:stable` only moves on a meaningful release, the router never re-pulls
|
||||
for build-system-only changes — see
|
||||
[DESIGN.md → Versioning & releases](DESIGN.md#versioning--releases).
|
||||
|
||||
> The digest fetch/compare logic is verified against the registry; the RouterOS
|
||||
> container/file API calls (marked in the script) should be smoke-tested once on
|
||||
> your device, since those idioms vary slightly by RouterOS version.
|
||||
|
||||
## MagicDNS
|
||||
|
||||
To use MagicDNS name resolution, configure MikroTik's DNS to forward `.ts.net`
|
||||
queries to Tailscale's magic DNS resolver:
|
||||
|
||||
```
|
||||
/ip dns static
|
||||
add name="ts.net" type=FWD forward-to=100.100.100.100 match-subdomain=yes
|
||||
```
|
||||
|
||||
When this is configured, you can connect to other tailscale machines using
|
||||
`[device name].[tailnet name].ts.net`. You can see and change assigned
|
||||
Tailnet DNS name in Tailscale admin panel under DNS tab.
|
||||
|
||||
## Logging
|
||||
|
||||
The container logs to the RouterOS log (topic `container`) via `logging=yes`.
|
||||
|
||||
Upstream `tailscaled` is notoriously chatty: by default it would emit a line
|
||||
for every accepted connection (`Accept: TCP{...}`), every netcheck report, and
|
||||
every WireGuard handshake/keepalive — several lines per minute on an active
|
||||
node ([tailscale#12158](https://github.com/tailscale/tailscale/issues/12158)).
|
||||
This image filters those verbose (`[v1]`/`[v2]`-tagged) messages out at the
|
||||
source, so only meaningful messages (startup, auth, route changes, warnings,
|
||||
errors) reach the RouterOS log. See
|
||||
[DESIGN.md → Log verbosity filtering](DESIGN.md#log-verbosity-filtering) for
|
||||
how and why.
|
||||
|
||||
To temporarily get the verbose logs back for debugging (e.g. NAT-traversal
|
||||
issues), set the `TS_LOG_VERBOSITY` environment variable and recreate the
|
||||
container with the envlist attached:
|
||||
|
||||
```
|
||||
/container/envs/add list=tailscale_envs name=TS_LOG_VERBOSITY value=1
|
||||
/container/set [find where name=tailscale] envlist=tailscale_envs
|
||||
/container/stop [find where name=tailscale]
|
||||
/container/start [find where name=tailscale]
|
||||
```
|
||||
|
||||
Any value ≥ 1 disables the filter (and raises the daemon's own verbosity by
|
||||
the same amount). Remove the variable and restart to silence it again:
|
||||
|
||||
```
|
||||
/container/envs/remove [find where name=TS_LOG_VERBOSITY]
|
||||
/container/stop [find where name=tailscale]
|
||||
/container/start [find where name=tailscale]
|
||||
```
|
||||
|
||||
## Updating
|
||||
|
||||
You don't normally do anything: when a new release is published, the
|
||||
auto-update script ([step 6](#6-enable-automatic-updates)) detects the changed
|
||||
`:stable` image on its next scheduled run and recreates the container. Your
|
||||
node identity and settings persist across the update via the state mount.
|
||||
|
||||
To force an immediate check instead of waiting for the schedule:
|
||||
|
||||
```
|
||||
/system/script/run update-tailscale
|
||||
```
|
||||
|
||||
To pin a specific version instead of tracking `:stable`, set `remote-image` (and
|
||||
the script's `imageRef`) to an immutable tag like
|
||||
`...mikrotik-tailscale:v1.98.3-mt.1`.
|
||||
@@ -0,0 +1,45 @@
|
||||
// Copyright (c) mikrotik-tailscale build. Injected at image build time.
|
||||
// SPDX-License-Identifier: BSD-3-Clause
|
||||
|
||||
//go:build ts_omit_logtail
|
||||
|
||||
package main
|
||||
|
||||
// When logtail is compiled out (ts_omit_logtail), logpolicy is never
|
||||
// installed (see run() in tailscaled.go: `if buildfeatures.HasLogTail`),
|
||||
// so log.Printf output goes raw to stderr. Nothing parses the [v1]/[v2]
|
||||
// verbosity tags Tailscale embeds in log messages, which means every
|
||||
// verbose line (filter "Accept: TCP", "netcheck: [v1] report",
|
||||
// "wg: [v2]" handshakes/keepalives) is printed regardless of --verbose.
|
||||
//
|
||||
// This restores the equivalent of logtail's StderrLevel=0 behavior:
|
||||
// drop lines carrying a [v1]+ tag, unless TS_LOG_VERBOSITY is set to
|
||||
// 1 or higher (runtime escape hatch for debugging — no rebuild needed).
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"log"
|
||||
"os"
|
||||
)
|
||||
|
||||
var verboseLogTags = [][]byte{[]byte("[v1] "), []byte("[v2] "), []byte("[v3] ")}
|
||||
|
||||
type stderrVerbosityFilter struct{ w *os.File }
|
||||
|
||||
func (f stderrVerbosityFilter) Write(p []byte) (int, error) {
|
||||
for _, tag := range verboseLogTags {
|
||||
if bytes.Contains(p, tag) {
|
||||
// Claim success so the log package doesn't complain;
|
||||
// the line is intentionally discarded.
|
||||
return len(p), nil
|
||||
}
|
||||
}
|
||||
return f.w.Write(p)
|
||||
}
|
||||
|
||||
func init() {
|
||||
if v := os.Getenv("TS_LOG_VERBOSITY"); v != "" && v != "0" {
|
||||
return
|
||||
}
|
||||
log.SetOutput(stderrVerbosityFilter{os.Stderr})
|
||||
}
|
||||
+48
-7
@@ -7,17 +7,58 @@
|
||||
],
|
||||
"labels": ["dependencies"],
|
||||
"rebaseWhen": "behind-base-branch",
|
||||
"dockerfile": {
|
||||
"pinDigests": true
|
||||
},
|
||||
"customManagers": [
|
||||
{
|
||||
"customType": "regex",
|
||||
"description": "Update version ARGs annotated with a `# renovate:` comment (the dockerfile manager only handles FROM/image lines, not ARG values).",
|
||||
"managerFilePatterns": ["/(^|/)Dockerfile$/"],
|
||||
"matchStrings": [
|
||||
"#\\s*renovate:\\s*datasource=(?<datasource>\\S+)\\s+depName=(?<depName>\\S+)(?:\\s+packageName=(?<packageName>\\S+))?(?:\\s+versioning=(?<versioning>\\S+))?\\s+ARG \\w+=(?<currentValue>\\S+)"
|
||||
],
|
||||
"matchStringsStrategy": "any"
|
||||
}
|
||||
],
|
||||
"packageRules": [
|
||||
{
|
||||
"matchManagers": ["dockerfile"],
|
||||
"description": "Keep base-image tags pinned to a digest.",
|
||||
"pinDigests": true
|
||||
},
|
||||
{
|
||||
"matchDatasources": ["github-releases"],
|
||||
"matchPackageNames": ["tailscale/tailscale"],
|
||||
"description": "TAILSCALE_VERSION ARG: only stable releases. Tailscale uses EVEN minor versions for stable (v1.98.x); ODD minors (v1.99.x) are unstable, so filter to even minors and ignore pre-releases.",
|
||||
"extractVersion": "^v(?<version>\\d+\\.\\d+\\.\\d+)$",
|
||||
"allowedVersions": "/^\\d+\\.\\d*[02468]\\.\\d+$/",
|
||||
"description": "TAILSCALE_VERSION ARG: only stable releases. Tailscale uses EVEN minor versions for stable (v1.98.x); ODD minors (v1.99.x) are unstable, so filter to even minors and ignore pre-releases. The `v` prefix is kept (no extractVersion) so the ARG value stays v-prefixed to match the git tags cloned in the Dockerfile.",
|
||||
"allowedVersions": "/^v\\d+\\.\\d*[02468]\\.\\d+$/",
|
||||
"ignoreUnstable": true
|
||||
},
|
||||
{
|
||||
"matchDatasources": ["github-releases"],
|
||||
"matchPackageNames": ["tailscale/tailscale"],
|
||||
"description": "Automerge all stable Tailscale releases (patch AND minor) once the PR build passes.",
|
||||
"matchUpdateTypes": ["minor", "patch"],
|
||||
"automerge": true
|
||||
},
|
||||
{
|
||||
"matchManagers": ["dockerfile"],
|
||||
"matchPackageNames": ["golang", "alpine"],
|
||||
"description": "Automerge PATCH-only bumps of build components (Go/Alpine) once the PR build passes; review minor/major manually.",
|
||||
"matchUpdateTypes": ["patch"],
|
||||
"automerge": true
|
||||
},
|
||||
{
|
||||
"matchDatasources": ["docker"],
|
||||
"matchPackageNames": ["busybox"],
|
||||
"description": "busybox ARG (custom manager): automerge PATCH bumps once the PR build passes; review minor/major manually.",
|
||||
"matchUpdateTypes": ["patch"],
|
||||
"automerge": true
|
||||
},
|
||||
{
|
||||
"matchManagers": ["dockerfile"],
|
||||
"matchUpdateTypes": ["digest", "pinDigest"],
|
||||
"description": "Automerge base-image digest refreshes (same tag, new sha256) once the PR build passes.",
|
||||
"automerge": true
|
||||
}
|
||||
]
|
||||
],
|
||||
"automergeType": "pr",
|
||||
"platformAutomerge": true
|
||||
}
|
||||
@@ -0,0 +1,230 @@
|
||||
# =============================================================================
|
||||
# mikrotik-tailscale: automatic container update check
|
||||
# =============================================================================
|
||||
# Checks the Gitea registry for a new :stable image and, only if the published
|
||||
# image actually changed, recreates the container. Designed for RouterOS 7.x
|
||||
# (tested target: 7.23, arm64). Requires RouterOS >= 7.23 for the container
|
||||
# restart-policy properties (and >= 7.13 for the :deserialize command used to
|
||||
# parse the registry token JSON).
|
||||
#
|
||||
# HOW IT DECIDES "something changed":
|
||||
# It fetches the manifest digest of the :stable tag from the registry and
|
||||
# compares it to the digest stored from the last successful deploy. The
|
||||
# :stable tag only moves on a MEANINGFUL release (Tailscale bump -> mt.1, or a
|
||||
# manual mt.N); dependency-only rebuilds never republish, so the digest is a
|
||||
# reliable "should I update" signal. No update -> no pull -> no flash wear.
|
||||
#
|
||||
# AUTH:
|
||||
# The Gitea package is public, but the Docker v2 API still needs a bearer
|
||||
# token. Gitea issues an anonymous token from /v2/token for public repos, so
|
||||
# no credentials are stored here.
|
||||
#
|
||||
# INSTALL (one-time):
|
||||
# 1. Edit the CONFIG section below to match your deployment.
|
||||
# 2. Upload this file to the router, then create a NAMED SCRIPT from it:
|
||||
# /system/script/add name=update-tailscale \
|
||||
# source=[/file/get update-tailscale.rsc contents]
|
||||
# NOTE: do NOT use "/import file=update-tailscale.rsc" — :import merely
|
||||
# *executes* the file's commands once (running an update immediately); it
|
||||
# does NOT create a reusable /system/script object. The scheduler below
|
||||
# runs the script by name, so it must exist as a named script.
|
||||
# (If you later edit the file, re-run the add with the ; replace it via
|
||||
# /system/script/set, or remove+add.)
|
||||
# 3. Schedule it: see the /system/scheduler command at the bottom of this file.
|
||||
#
|
||||
# The script is idempotent and safe to run on a schedule.
|
||||
# =============================================================================
|
||||
|
||||
:local scriptName "update-tailscale"
|
||||
|
||||
# ----------------------------------------------------------------------------
|
||||
# CONFIG -- edit these to match your setup
|
||||
# ----------------------------------------------------------------------------
|
||||
# Registry / image
|
||||
:local regHost "gitea.lumpiasty.xyz"
|
||||
:local repo "lumpiasty/mikrotik-tailscale"
|
||||
:local tag "stable"
|
||||
# Full image reference RouterOS uses to pull (must include the tag).
|
||||
:local imageRef "gitea.lumpiasty.xyz/lumpiasty/mikrotik-tailscale:stable"
|
||||
|
||||
# Where the last-deployed digest is remembered between runs.
|
||||
:local stateFile "tailscale-image.digest"
|
||||
|
||||
# --- /container add parameters (must match your working deployment) ---------
|
||||
# These are reused verbatim when recreating the container. They MUST match the
|
||||
# values used in the deployment guide (docs/USAGE.md) so the new container is
|
||||
# identical to the one being replaced.
|
||||
:local cName "tailscale"
|
||||
:local cRootDir "tailscale/root"
|
||||
:local cMountList "tailscale_state"
|
||||
:local cInterface "veth-tailscale"
|
||||
:local cLogging yes
|
||||
:local cStartOnBoot yes
|
||||
# Restart the container automatically if tailscaled crashes (tailscaled is
|
||||
# PID 1; if it dies the container stops). on-failure restarts only on abnormal
|
||||
# exit (a manual /container/stop stays stopped); 10s is a gentle backoff.
|
||||
# Requires RouterOS >= 7.23.
|
||||
:local cRestartPolicy "on-failure"
|
||||
:local cRestartInterval "10s"
|
||||
# ----------------------------------------------------------------------------
|
||||
|
||||
:log info "$scriptName: checking for image updates"
|
||||
|
||||
# --- 0. Don't run concurrently -----------------------------------------------
|
||||
# A slow pull/extract could overlap the next scheduled run; bail if another
|
||||
# instance of this script is already running.
|
||||
:if ([/system/script/job/print count-only as-value where script=[:jobname]] > 1) do={
|
||||
:log warning "$scriptName: another instance is already running; exiting"
|
||||
:error "already running"
|
||||
}
|
||||
|
||||
# --- 1. Get an (anonymous) registry bearer token ----------------------------
|
||||
# The response body is JSON ({"token":"..."}); parse it with :deserialize
|
||||
# (RouterOS >= 7.13) instead of fragile string slicing.
|
||||
#
|
||||
# NOTE: the URL has NO "&service=..." parameter on purpose. In RouterOS "&" is
|
||||
# the logical-AND operator and breaks the url= argument ("Please provide IP
|
||||
# address or host"), even inside a quoted string. Gitea issues a usable token
|
||||
# from just ?scope=..., so the service= param is omitted to avoid the "&".
|
||||
:local tokenUrl "https://$regHost/v2/token?scope=repository:$repo:pull"
|
||||
:local token ""
|
||||
:onerror e in={
|
||||
:local tr [/tool fetch url=$tokenUrl as-value output=user]
|
||||
:if (($tr->"status") = "finished") do={
|
||||
:local obj [:deserialize from=json value=($tr->"data")]
|
||||
:set token ($obj->"token")
|
||||
}
|
||||
} do={
|
||||
:log error "$scriptName: token fetch failed: $e"
|
||||
:error "token fetch failed"
|
||||
}
|
||||
:if ([:typeof $token] != "str" || [:len $token] = 0) do={
|
||||
:log error "$scriptName: could not parse registry token"
|
||||
:error "no token"
|
||||
}
|
||||
|
||||
# --- 2. Fetch the :stable manifest and read its digest -----------------------
|
||||
# We request the OCI index media type and read the Docker-Content-Digest
|
||||
# response header, which is the canonical manifest-list digest.
|
||||
:local manUrl "https://$regHost/v2/$repo/manifests/$tag"
|
||||
:local hdrs "Authorization:Bearer $token,Accept:application/vnd.oci.image.index.v1+json"
|
||||
:local newDigest ""
|
||||
:onerror e in={
|
||||
:local mr [/tool fetch url=$manUrl http-header-field=$hdrs as-value output=user-with-headers]
|
||||
:if (($mr->"status") = "finished") do={
|
||||
# output=user-with-headers returns ALL response headers as one flat string,
|
||||
# ";"-separated, e.g. "Name: value;Name: value;...". There is no keyed
|
||||
# lookup, so we substring-match. Two pitfalls this handles:
|
||||
# - Header NAME case is not guaranteed (HTTP/2 lowercases names; header
|
||||
# names are case-insensitive anyway) -> lowercase the blob first.
|
||||
# - Some header VALUES contain ";" (e.g. strict-transport-security:
|
||||
# "max-age=...; includeSubDomains"). We anchor on the digest key and
|
||||
# read to the next ";"; the digest value (sha256:<hex>) has no ";",
|
||||
# so this is safe.
|
||||
:local rh [:convert transform=lc ($mr->"http-headers")]
|
||||
:local key "docker-content-digest: "
|
||||
:local p [:find $rh $key]
|
||||
:if ([:typeof $p] != "nil") do={
|
||||
:local rest [:pick $rh ($p + [:len $key]) [:len $rh]]
|
||||
:local q [:find $rest ";"]
|
||||
:if ([:typeof $q] = "nil") do={ :set q [:len $rest] }
|
||||
:set newDigest [:pick $rest 0 $q]
|
||||
}
|
||||
}
|
||||
} do={
|
||||
:log error "$scriptName: manifest fetch failed: $e"
|
||||
:error "manifest fetch failed"
|
||||
}
|
||||
:if ([:len $newDigest] = 0) do={
|
||||
:log error "$scriptName: could not read Docker-Content-Digest"
|
||||
:error "no digest"
|
||||
}
|
||||
:log info "$scriptName: registry :stable digest = $newDigest"
|
||||
|
||||
# --- 3. Compare with the last-deployed digest --------------------------------
|
||||
:local oldDigest ""
|
||||
:if ([:len [/file find where name=$stateFile]] > 0) do={
|
||||
:set oldDigest [/file get [/file find where name=$stateFile] contents]
|
||||
}
|
||||
|
||||
:if ($newDigest = $oldDigest) do={
|
||||
:log info "$scriptName: image unchanged; nothing to do"
|
||||
:error "noop"
|
||||
}
|
||||
:log info "$scriptName: image changed ($oldDigest -> $newDigest); updating"
|
||||
|
||||
# --- 4. Recreate the container -----------------------------------------------
|
||||
:local cid [/container find where name=$cName]
|
||||
:if ([:len $cid] > 0) do={
|
||||
:log info "$scriptName: stopping and removing existing container"
|
||||
:onerror e in={ /container stop $cid } do={ :log warning "$scriptName: stop: $e" }
|
||||
# Retry the REMOVE itself until it succeeds (up to ~30s). /container/remove
|
||||
# errors while the container is still running, so retrying the remove is
|
||||
# self-correcting: it waits for the stop to settle without us having to know
|
||||
# the exact status string. On success :retry stops; on persistent failure the
|
||||
# do={} block runs.
|
||||
:onerror e in={
|
||||
:retry command={ /container remove $cid } delay=1 max=30
|
||||
} do={
|
||||
:log error "$scriptName: remove failed after retries: $e"
|
||||
:error "remove failed"
|
||||
}
|
||||
}
|
||||
|
||||
# Pull happens implicitly on add when remote-image is given.
|
||||
:log info "$scriptName: adding new container from $imageRef"
|
||||
:onerror e in={
|
||||
/container add \
|
||||
remote-image=$imageRef \
|
||||
interface=$cInterface \
|
||||
root-dir=$cRootDir \
|
||||
mountlists=$cMountList \
|
||||
logging=$cLogging \
|
||||
start-on-boot=$cStartOnBoot \
|
||||
restart-policy=$cRestartPolicy \
|
||||
restart-interval=$cRestartInterval \
|
||||
name=$cName
|
||||
} do={
|
||||
:log error "$scriptName: container add failed: $e"
|
||||
:error "add failed"
|
||||
}
|
||||
|
||||
# Start the container. After /container/add the image is still extracting, and
|
||||
# /container/start errors until extraction finishes, so we retry the START
|
||||
# itself (up to ~4min) — self-correcting, no need to poll an exact status
|
||||
# string. (If start-on-boot causes RouterOS to auto-start it once extraction
|
||||
# completes, a later manual start simply errors and :retry stops once it's
|
||||
# running / the do={} block runs.)
|
||||
:local ncid [/container find where name=$cName]
|
||||
:onerror e in={
|
||||
:retry command={ /container start $ncid } delay=2 max=120
|
||||
} do={
|
||||
:log warning "$scriptName: container start did not succeed within timeout (may still be extracting or already running): $e"
|
||||
}
|
||||
|
||||
# --- 5. Persist the new digest so we don't update again next run -------------
|
||||
# We record the digest once the new container exists. Even if the start above
|
||||
# is still settling, the container is created from the new image, so we should
|
||||
# not re-pull on the next run.
|
||||
:if ([:len [/file find where name=$stateFile]] > 0) do={
|
||||
/file set [/file find where name=$stateFile] contents=$newDigest
|
||||
} else={
|
||||
/file add name=$stateFile contents=$newDigest
|
||||
}
|
||||
:log info "$scriptName: updated to $newDigest"
|
||||
|
||||
# =============================================================================
|
||||
# SCHEDULING (after creating the named script per INSTALL step 2 above)
|
||||
# =============================================================================
|
||||
# Create a scheduler entry that runs the named script daily:
|
||||
#
|
||||
# /system/scheduler add name=update-tailscale interval=1d \
|
||||
# on-event="/system/script run update-tailscale" \
|
||||
# comment="Check for mikrotik-tailscale image updates"
|
||||
#
|
||||
# Adjust interval to taste (e.g. 6h, 1d, 7d). The check is cheap (one small
|
||||
# HTTPS request); it only pulls/recreates when the :stable digest changed.
|
||||
#
|
||||
# To test once, by hand:
|
||||
# /system/script run update-tailscale
|
||||
# =============================================================================
|
||||
Reference in new issue
Block a user