Networking

Everything below is built from these. None are complicated once the metaphor lands.

You are at a coffee shop and want a file from ~/data/school-work. You type ssh admin@homie.tailnet-name.ts.net.

The surprise: neither Caddy nor Docker is involved at any point. Worth following, because it clarifies what each is actually for.

1. On your Mac — the name resolves privately

   Tailscale intercepts the lookup for homie.tailnet-name.ts.net and answers 100.64.0.10 itself. This name does not exist on the public internet; ask any normal DNS server and you get nothing.

2. Between the machines — a direct encrypted path is negotiated

   Both already hold outbound connections to Tailscale’s coordination service, so they can be introduced and then punch a path straight to each other. Everything is encrypted with WireGuard before it leaves the Mac. The coffee shop, your ISP and Tailscale itself carry sealed traffic they cannot read. If no direct path can be found, an encrypted relay is used instead — slower, still private.

3. Arriving at homie — it lands on tailscale0

   homie has two interfaces: wlp4s0 facing the house and tailscale0 facing the tailnet. This traffic arrives on tailscale0, is decrypted, and is addressed to port 22.

4. On homie — SSH answers, and you get the files

   ufw permits SSH on every interface, so it passes; your identity is proven with a key rather than a password. sshd runs on the host, not in a container — so no Docker networking, no port publishing, no Caddy. ~/data/school-work is an ordinary directory on the disk. Copy with scp or sftp and you are done.

5. Meanwhile, separately — Syncthing is watching that same directory

   That folder is also shared into the Syncthing container. Anything you drop there gets picked up and synced to your other devices — not because SSH told it to, but because it is the same folder on disk viewed from two places.

tailnet LAN VPN tunnel

One file’s whole life: requested from a laptop over the tunnel, downloaded through a VPN, filed onto disk, then played on a TV that reaches the server a completely different way.

1. You open the downloader from your laptop

   Its control panel sits behind Caddy on the tailnet at port 8444, exactly like Syncthing’s — reachable by you from anywhere, invisible to everyone in the house. From the house WiFi the address returns nothing at all.

   It needed one thing Jellyfin and Syncthing did not. qBittorrent checks that the port in the browser’s Host header matches the port it is itself listening on, and rejects the request when they differ — which is exactly what a proxy on a different port causes. So Caddy rewrites three headers (Host, Origin, Referer) to http://homie.tailnet-name.ts.net:8080, the origin qBittorrent believes it serves. Both of its protections stay switched on. Your browser is still on HTTPS at 8444; only the internal hop is rewritten.

2. The download leaves through a VPN, not your home connection

   Every packet qBittorrent sends leaves through a WireGuard tunnel to a NordVPN server, and the address every peer in the swarm records is Nord’s, never the house’s. §04 is how that is enforced.

3. The finished file lands in the media folder, correctly named

   The downloader writes into /mnt/t7/… through a writable bind. Jellyfin’s view of that same folder is read-only — one directory, two containers, different permissions, deliberately.

   Naming decides whether any of this works. A release arrives as Harbor.Town.S02E03.1080p.WEB-DL.x265-GROUP.mkv, which Jellyfin cannot identify. On completion qBittorrent runs a script that rewrites it to Harbor Town (2022) - S02E03.mkv and moves it into place — and because downloads and library share one drive, that move is an instant rename that copies no bytes.

   The script refuses to guess. A release it cannot confidently identify is left exactly where it is, with the reason written to config/qbittorrent/qbt-file.log. A file that waits is a minute’s work; a file misnamed into the wrong show is not.

4. Jellyfin notices on its next scan

   It works out what the file is and fetches artwork and details from the internet. This is Jellyfin reaching out; nothing reached in.

5. The TV connects straight to homie — no proxy, no tunnel

   The TV opens the Jellyfin app and connects to 192.168.1.10:8096 over the house WiFi. It is not on the tailnet and does not go through Caddy. This is the shared door, and it is plain HTTP — putting the TV behind Caddy would mean installing a certificate on it and on every roommate device.

6. Docker hands the connection to the container

   Jellyfin does not sit on the network directly; it lives on a private Docker network, and Docker forwards anything arriving on the host’s port 8096 into the container. That forwarding is also why the firewall cannot be trusted to protect container ports, and why each port is pinned to a specific address instead.

7. Playback: ship it as-is, or convert it on the fly

   If the TV can handle the file’s format, Jellyfin ships the bytes untouched — cheap, and the best outcome. If not, it converts while playing, on the laptop’s built-in video engine rather than the CPU. On a four-thread machine what matters is that the work lands on dedicated silicon instead of eating every core. homie-check reports which one a live playback is actually using.

8. And at the same time — you can watch the same library over the tunnel

   From outside the house you reach Jellyfin at https://homie.tailnet-name.ts.net — through the tunnel, through Caddy, fully encrypted. Same server, same library, different door. The two paths coexist without either knowing about the other.

qBittorrent has no network of its own. It shares Gluetun’s entirely — one Linux network namespace, so the only interfaces it can see are loopback and tun0, the mouth of a WireGuard tunnel to a NordVPN server.

This is a kill switch by construction. If the VPN drops, qBittorrent does not fall back to the ordinary connection — it has no interface to fall back to. Tested by stopping Gluetun with a download running: traffic stopped, and so did DNS.

The mechanism is not the one you would guess

It does not work by replacing the default route. Inside the namespace the default route still points at the Docker bridge. What diverts internet-bound traffic is a policy rule at priority 101 matching WireGuard’s firewall mark. You can watch the kernel decide:

$ docker exec gluetun ip route get 1.1.1.1
1.1.1.1 dev tun0 table 51820 src 10.5.0.2

$ docker exec gluetun ip route get 172.18.0.2
172.18.0.2 dev eth0 src 172.18.0.5

Two other details cost time and are worth keeping: Gluetun names the interface tun0 even on WireGuard, not wg0; and Nord permits P2P only on certain servers, so SERVER_CATEGORIES=P2P constrains every pick including reconnects. SERVER_COUNTRIES=United States was added after a reconnect landed in Edinburgh and every peer round trip crossed the Atlantic.

This is the part that stays fuzzy longest, so it gets its own section. The thing to hold on to: who starts the conversation determines everything.

Your router runs NAT. It has one public address and a table of ongoing conversations. When homie sends a packet out, the router writes a row — this inside address and port is talking to that outside address and port — rewrites the source to the public IP, and sends it. Replies matching that row get translated back and delivered. Replies matching no row have no destination inside the house, so they are dropped: the router cannot know which of your devices they were for.

The asymmetry is the whole story. Outbound connections carry data in both directions, which is why downloading works perfectly with no forwarded port. What you lose without one is only the ability for peers to initiate — so you upload to fewer of them than you otherwise could.

The design in one table. Every row was verified by connecting from both sides; bin/homie-check re-tests them on every run.

The right-hand column is entirely no, and that is the headline. The router forwards no ports at all. Remote access works because your devices and homie both reach outward and meet in the middle — never because anything was opened for the world to knock on.

Every network this machine is on

One line each