pi5-silt-gateway

Raspberry Pi 5: flashing and first boot

You need: a microSD card (1 GB or larger), a card reader, Ethernet, and the official 27 W USB-C power supply. Optional: a micro-HDMI cable for a screen, and a Raspberry Pi Debug Probe for the serial console.

1. Check the download. Compare its SHA-256 with the one on this page:

shasum -a 256 sdcard.img        # macOS
sha256sum sdcard.img            # Linux

2. Write it to the card. This erases the card. Find the card's device first and make sure it is the card, not a disk you need.

# macOS: find the card (e.g. /dev/disk6), then
diskutil list external
diskutil unmountDisk /dev/diskN
sudo dd if=sdcard.img of=/dev/rdiskN bs=4m && sync
diskutil eject /dev/diskN

# Linux: find the card (e.g. /dev/sdX), then
lsblk
sudo dd if=sdcard.img of=/dev/sdX bs=4M conv=fsync status=progress

Raspberry Pi Imager works too: choose Use custom and pick sdcard.img.

3. Boot. Insert the card, connect Ethernet, then power. The board asks your network for an address (DHCP) as it starts.

4. Find it. Your router's client list shows it, or scan your network:

sudo nmap -sn 192.168.1.0/24 | grep -B2 -i 'raspberry'

Serial console. The Pi 5 has a 3-pin UART connector between its two micro-HDMI ports. Connect a Raspberry Pi Debug Probe there and open it at 115200 baud (picocom -b 115200 /dev/ttyACM0, or /dev/cu.usbmodem* on a Mac). Kernel messages and a login prompt appear there.

# claim: claim a fresh board from a browser

A board built with feature:claim boots with nobody's key on it and no way in over the network. Its claim page, on port 8022, takes your SSH public key once:

boot ─▶ S49silt-claim prints   Claim page: OK, claim this board at:
                                 http://192.168.68.140:8022/  (eth0)
open it ─▶ paste ~/.ssh/id_ed25519.pub ─▶ Claim
        ─▶ /root/.ssh/authorized_keys written, the page stops
ssh root@192.168.68.140   ← your key, and only your key

• SSH never takes a password. dropbear runs with -s (/etc/default/dropbear), root's included, so before the claim nobody gets in over the network and after it only the key given on the page does.
• The first visitor claims the board, as the first visitor chooses Silt Gateway's password. That is a choice for a bench or a home network.
• The serial console still logs in. Whoever holds the board owns it, and the console is the way back for an owner who loses the key: delete /root/.ssh/authorized_keys and reboot, and the page is back.
• Port 8022, not 80, so the page sits beside an image's own page (Silt Gateway's is on 80) without either knowing about the other.
• Nothing is baked in. Every board flashed from one image starts the same; the key is the board's, not the image's. dev-ssh bakes a key in at build time instead. Use one or the other.

The page checks a key the way dropbear will read it (its type, and every field its blob should hold) and shows its SHA256 fingerprint, as ssh-keygen -lf ~/.ssh/id_ed25519.pub prints it, so you can see it is yours. A pasted private key is refused with a reason.

On an A/B board

An update replaces the root filesystem, and the key with it, which would open a claimed board to claiming again. The ab pack keeps root's keys on the data partition (/root/.ssh links to /data/ssh), so a board is claimed once and stays claimed through every update.

Adding it to an image

One word in the image's compose:

(compose image:pi5-tailscale feature:gateway feature:claim)

silt-claimd is standard-library Go, like silt-gatewayd: nothing to fetch at build time.

The screenshots

screens/shoot.mjs takes them from the real silt-claimd with a key made and thrown away on the spot (npm i playwright@1.48.2 && node shoot.mjs in screens/). Retake them when the page changes.

# gateway: Silt Gateway

A board that joins a tailnet and shares its network, set up from a browser. Plug it in, open http://<board>/, choose a password, and join: with an auth key, or by following a sign-in link. On Tailscale's coordination server, or on your own (Headscale), by giving its URL. Then choose what the board offers:

• subnet routes: the networks it is on, reachable from anywhere on the tailnet with nothing installed on the machines in them;
• the exit node: devices on the tailnet send their internet traffic out through this board;
• other routers' routes: whether this board reaches what other gateways share.

Each route shows whether the control server has approved it yet.

How it fits

image:pi*-tailscale  ── feature:tailscale  tailscaled, its init script, CA certs,
                                           a clock, TUN and NAT in the kernel
feature:gateway      ── silt-gatewayd      this page, on :80
feature:claim        ── silt-claimd        SSH key-only; the owner's key from a page on :8022

silt-gatewayd keeps no Tailscale state. tailscaled's state file holds the node key, the control server and the routes; the page reads them with tailscale status --json and tailscale debug prefs on every request and changes them with tailscale login and tailscale set, so nothing can drift. The only thing it keeps is the owner's password, as a PBKDF2 hash in /var/lib/silt-gateway/password.

The kernel's forwarding is switched on whenever tailscaled holds a route or the exit node (and after a reboot, from what tailscaled holds), never off.

Images

Trying it in QEMU

Build it like any image; the output has Image, rootfs.ext4 and Buildroot's own start-qemu.sh:

# on the build machine (once: sudo apt install qemu-system-arm)
kconf build qemu-silt-gateway -o out/qemu-silt-gateway
cd out/qemu-silt-gateway/images
./start-qemu.sh --use-system-qemu -m 1024 -monitor unix:/tmp/gw-qemu.sock,server,nowait

The guest's network is QEMU's user network (eth0), which reaches the internet but takes no connections. Forward the page to the build machine from another shell, through QEMU's monitor:

echo "hostfwd_add eth0 tcp:127.0.0.1:8080-:80" | nc -NU /tmp/gw-qemu.sock
echo "hostfwd_add eth0 tcp:127.0.0.1:8022-:8022" | nc -NU /tmp/gw-qemu.sock   # claim page
echo "hostfwd_add eth0 tcp:127.0.0.1:2222-:22" | nc -NU /tmp/gw-qemu.sock     # ssh, once claimed

and from your own machine, ssh -L 8080:127.0.0.1:8080 to the build machine and open http://localhost:8080/. Joining works as on a board; routes to the QEMU user network (10.0.2.0/24) are suggested, which is enough to see approval work.

Security

• The first visitor chooses the password, as with most home appliances: set it before putting the board on a network you don't trust. The same holds for the SSH key on the claim page (feature:claim, see claim/README.md).
• Sessions are an HttpOnly, SameSite=Strict cookie; every change is a JSON request, which a page on another site can't send with it.
• Five wrong passwords in a minute lock sign-in for the rest of that minute.
• To reset a forgotten password, delete /var/lib/silt-gateway/password on the board (serial console) and reload the page.

Name

"Silt Gateway" is a working name. Tailscale is a trademark of Tailscale Inc.; this product uses the open-source Tailscale client and is not affiliated with it. Check its terms before selling a device built on it.

Development

cd br2-external/package/silt-gateway/src
go test ./...
go run ./cmd/silt-gatewayd -http 127.0.0.1:8080 -data /tmp/gw \
  -tailscale "$(command -v tailscale)" -socket /var/run/tailscale/tailscaled.sock

The tests read internal/tailnet/testdata, captured from tailscale 1.78.1 (the version Buildroot 2025.02.16 ships).

The screenshots

screens/shoot.mjs takes them from the real page, served by silt-gateway-demo over a stand-in for tailscaled on an example tailnet (npm i playwright@1.48.2 && node shoot.mjs in screens/). The demo is not part of the image: the package builds ./cmd/silt-gatewayd only.