Clicking "I accept" on a captive portal — for a headless server

Captive portals are a fact of life on guest wifi: connect, get redirected to a page, tick a box or log in, and you're online. Fine for a laptop. A proper pain for a headless server that has no browser and no one sitting in front of it. Here's the trick I used to get a headless box past a per-MAC portal, and it generalises nicely.

Why you can't just do it from your laptop

The portal authorises per device — it remembers the MAC (and/or IP) that completed the login and lifts the walled garden for that client. So logging in from your laptop's browser authorises your laptop, not the server. The server's own connection is still walled. You have to make the login traffic originate from the server itself.

The trick: proxy a browser through the server

If you can SSH to the box (over a wired path, a second interface, whatever), turn it into a SOCKS proxy:

ssh -D 1080 -N user@server

Now anything you send into localhost:1080 is originated by the server and exits its network connection. Point a browser at that proxy and, from the portal's point of view, it's the server knocking — correct MAC, correct session. Chromium does remote DNS over SOCKS5, so name resolution goes out the server's link too.

I drove it headlessly with Playwright through the proxy:

chromium --proxy-server="socks5://localhost:1080"
# or, in Playwright, launch with proxy={"server":"socks5://localhost:1080"}

Navigate to anything over plain HTTP (http://neverssl.com is the classic), let the portal redirect fire, accept the terms / sign in, and the gateway authorises the server's MAC. Once that's done you can tear the proxy and browser down entirely — the authorisation lives at the gateway, keyed to the MAC, not in the browser session.

Making it stick

Two wrinkles for unattended use:

• Sessions expire. Wrap the same headless flow in a small script and have a watchdog run it whenever a connectivity check (curl -s -o /dev/null -w '%{http_code}' http://connectivitycheck.gstatic.com/generate_204, want 204) comes back non-204. A persistent browser profile keeps any "remember me" cookie between runs.
• Registration vs. login. Some portals (Sky's "The Cloud", BT Wi-fi and friends) want an account. A throwaway mailbox with an API — I used mail.tm — lets you register and, if needed, script the catching of a verification email.

It feels a bit like sawing through the bars from the inside, but it's entirely above board — you're authenticating the device that's actually using the connection. The SOCKS-proxy-through-the-box idea is the reusable part; keep it for the next headless thing stuck behind a portal.

I hope this resolves any difficulties you may be experiencing. Enjoy!