Skip to content
Jeremy Blum edited this page Nov 13, 2026 · 6 revisions

This page explains what RWSOLS protects, what each remote access mode exposes, and how the hostname allowlist and Cloudflare Access work. It is a description of what the code does, not a guarantee. Read it alongside Remote Access with Cloudflare Tunnel and Adding Cloudflare Access.

Threat model, briefly

RWSOLS is a small web page that can wake up and put to sleep computers on your home network. There are no user accounts: one shared passphrase (stored only as a hash) protects the wake, sleep and status actions. What I'm worried about, roughly in order:

  1. Strangers on the internet finding the page and guessing the passphrase, or poking at the web server. This depends on how you expose it (see below).
  2. Eavesdroppers reading the passphrase in transit. That's what HTTPS is for.
  3. DNS rebinding. A malicious web page, opened in a browser on your own network, can use a domain name it controls and then re-point that name at your Pi's LAN address. The browser then happily talks to the Pi on the page's behalf, from inside your network. The hostname allowlist is the defense for this.
  4. Someone going around your front door, for example reaching the Pi's web server directly when a login is supposed to be in front of it. Cloudflare Access verification is the defense for this.

What RWSOLS can't do for you: protect a weak passphrase, or protect you if someone is already on your LAN with a browser (LAN visitors can reach the LAN listener directly, and only need the passphrase).

What each mode exposes

Mode What's reachable from the internet Notes
None (LAN only) Nothing. Only devices on your network can reach RWSOLS. The allowlist still helps against rebinding.
Port forwarding (legacy) Your Pi's Apache, on ports 80/443 of your home IP. Your home IP is published through DDNS and your web server faces the internet. Anyone who finds the hostname can reach the login page. Use HTTPS.
Cloudflare Tunnel Nothing inbound. The Pi connects out to Cloudflare. Your home IP isn't in DNS and you have no open ports. Cloudflare terminates HTTPS for your hostname and sees the traffic. Anyone who finds the hostname can reach the login page, unless you add Access.
Cloudflare Tunnel + Access Nothing inbound. Visitors must also pass Cloudflare Access's login. RWSOLS verifies Access's signed token itself.

In Tunnel mode, cloudflared connects to a separate Apache virtual host that listens on the loopback address only (127.0.0.1:8080 by default). It is not reachable from your LAN. The regular LAN listener is unchanged, so LAN users keep using it, and the LAN listener does not require Access: anyone on your LAN who reaches the Pi under one of its LAN names still only needs the passphrase.

The hostname allowlist

When $ALLOWED_HOSTS lists at least one name, RWSOLS only answers requests whose Host header is on the list. This is what stops a rebinding page: its requests carry the attacker's domain name in the Host header, which isn't on your list.

  • Rejected requests get HTTP 421 with an empty body, for every path, including images, CSS and other static files.
  • Matching is exact: case-insensitive, the port and one trailing dot are ignored, and there are no wildcards. A bare IP is rejected unless that exact IP is listed (LAN users can list the Pi's .local name, the local DNS name your router gives it, or its LAN IP). A missing Host header is rejected.
  • It is enforced by Apache and again by PHP. The Apache part is a generated file, /etc/apache2/conf-available/rwsols-allowed-hosts.conf, containing a server-level <If> block, so it applies to every virtual host, including the one that certbot creates. PHP checks the same list as a second layer.
  • $ALLOW_LOCALHOST additionally allows localhost, 127.0.0.1 and [::1].
  • Editing config.php by hand does not update Apache. Re-run python3 setup.py --remote-access afterwards.

It's off by default, and the wizard asks about it. If you turn it on, the wizard shows a multi-select list of candidate names, each with a reason: the tunnel hostname (required in Tunnel mode), the Pi's .local name, your router's local DNS name for the Pi (offered only when a reverse lookup of the Pi's LAN IP, or the Pi's hostname plus your network's DNS search domain, gives a name that resolves back to that IP), the LAN IP (unticked unless it was already on your list; if you tick it, reserve the address in your router so it does not change), names already on your list, and your dynamic DNS names (ticked in Port forwarding mode, listed but unticked otherwise). Type a to add any other name. With the allowlist on, anything you used to type to reach RWSOLS that isn't listed stops working. That's the point, but it's also the way to lock yourself out; see the recovery section below.

The TLS / SNI limitation

The allowlist works at the HTTP layer. When a browser connects over HTTPS, it first does a TLS handshake and names the site it wants (SNI). Apache still completes that handshake for an unlisted or missing SNI name and presents its certificate. Only the HTTP request that follows is refused with the 421. So an observer can still learn that something is listening and what certificate it presents, and a certificate issued for your hostname is visible to anyone who connects. Refusing the handshake itself would need a default virtual host with a dummy certificate, which conflicts with how certbot manages virtual hosts, so I haven't done it. In Tunnel mode this doesn't apply to the public side: Cloudflare handles TLS for your hostname.

Cloudflare Access verification

If you enable Access, you have two layers. Cloudflare checks who you are before passing the request to the Pi. RWSOLS then checks, for requests for the tunnel hostname or arriving on the tunnel listener, that the request carries a valid Cf-Access-Jwt-Assertion token.

  • Apache refuses requests with no such header (403), including for static files. The loopback virtual host does it for every Host it receives, and a server-level rule does it for the tunnel hostname on any other virtual host.
  • PHP verifies the token's RS256 signature against the keys at https://<team domain>/cdn-cgi/access/certs, then checks the audience ($ACCESS_AUD), the issuer (https://<team domain>) and the expiry and start times (60 seconds of leeway for clock differences). Failures get an empty 403.
  • The keys are cached for about an hour, and refetched at most about once a minute.
  • It fails closed. If Cloudflare's key endpoint is unreachable and the cached keys have expired, tunnel requests are denied. Setting only one of $ACCESS_TEAM_DOMAIN and $ACCESS_AUD also denies all tunnel requests.

Service tokens (for scripts and shortcuts) are described on the Access page.

Login throttling

RWSOLS limits passphrase guessing. After 5 wrong passphrases from one client address within 15 minutes, that address is locked out for 15 minutes. During the lockout the passphrase is not checked at all, so even the right one is refused, with the message "Too many incorrect passphrase attempts" and HTTP status 429. A correct passphrase before the limit resets the count.

  • The limit and the lockout time are $LOGIN_MAX_ATTEMPTS and $LOGIN_LOCKOUT_SECONDS in config.php. $LOGIN_MAX_ATTEMPTS = 0; turns it off. It is on by default, including for installs upgraded from a version without it.
  • The client address is the connecting IP. IPv6 addresses are counted per /64 network. For requests that arrive through the Cloudflare Tunnel, the visitor address that Cloudflare reports is used; on the normal LAN/port forwarding listener that header is ignored, because anyone could forge it.
  • Locked yourself out? Wait, or restart Apache (sudo systemctl restart apache2), which clears the counters.
  • This slows down guessing from one address. It does not stop an attacker who spreads guesses over many addresses, so a long passphrase still matters. Cloudflare Access in front of the tunnel is the stronger protection.
  • If the counter files cannot be written, RWSOLS does not lock anyone out (and logs that), so that a disk problem cannot lock you out of your own server.

File permissions

config.php holds the passphrase hash and the list of your machines. The setup script makes the served copy, /var/www/html/config.php, readable only by root and the web server (owner root, group www-data, mode 640). Each time the script replaces the web root it keeps the previous one as /var/www/html_backup_<date>; those folders contain older copies of config.php, so the script makes them readable only by root. Use sudo to look at either. The script does not delete old backups; remove the ones you no longer want with sudo rm -r.

Logging

RWSOLS writes to syslog, tag rwsols. View it with:

sudo journalctl -t rwsols -n 50

  • login lockout client=<ip> seconds=<n> when an address is locked out for too many wrong passphrases.
  • With $LOG_HOST_REJECTIONS = true: rejected request with disallowed Host "..." from <ip>.
  • With Access: denied tunnel request from <ip>: <reason> when PHP rejects a token, and, for each wake, sleep or status request made through Access, access identity "<email>" from <ip> POST action "<action>" computer "<n>".
  • Logging is rate limited: at most 10 lines per minute for each kind, then a one line summary of how many were suppressed. Log values are cleaned of unprintable characters and quotes before they are written.
  • Apache's own logs are in /var/log/apache2. The tunnel listener has its own, tunnel_access.log and tunnel_error.log. Requests refused by Apache itself (the allowlist, or a missing Access header) show up there, not as rwsols lines.

The passphrase is never logged.

Locked yourself out?

If you enabled the allowlist and can no longer reach RWSOLS (you typed the wrong names, or you're browsing by an IP or name that isn't listed), use SSH or a keyboard on the Pi. Any one of these fixes it:

  1. Re-run python3 setup.py --remote-access, and answer No to "Enable the hostname allowlist?" (choose 2). This is the cleanest way.
  2. Turn off the Apache half by hand, and edit the list:
    • sudo a2disconf rwsols-allowed-hosts && sudo systemctl reload apache2
    • Set $ALLOWED_HOSTS = array(); in both copies of config.php: the one in the repo folder (www/html/config.php) and the one in /var/www/html/config.php.
  3. If you only need a name added, add it to $ALLOWED_HOSTS in the repo's config.php and run python3 setup.py --remote-access.

If it's Access that's locking you out (403s), see the troubleshooting on the Access page. You can always reach RWSOLS on your LAN through its LAN name, as long as that name is allowed.

Other notes

  • The tunnel token is stored in /etc/cloudflared/rwsols-tunnel.env, readable only by root. The Cloudflare API token you give the wizard for the tunnel setup is held in memory and never written to disk. The one exception is the optional trusted LAN certificate: its renewals need a DNS-only API token, which is stored in /etc/letsencrypt/rwsols-cloudflare.ini, readable only by root, and removed again when you switch to another certificate choice. Give that token nothing but Zone > DNS > Edit and Zone > Zone > Read for the one zone. The wizard's state file (.rwsols_remote_access.json) records only what it created, with no secrets.
  • Keep your Pi updated. The setup script offers to do this for you: it installs Debian's unattended-upgrades, which installs security updates once a day, including updates from the Raspberry Pi package archive and, if you use a Cloudflare Tunnel, of cloudflared from Cloudflare's package repository. It can also restart the Pi at 04:00 on days when an update needs a restart (off unless you say yes; kernel and firmware updates do not take effect until a restart). Run python3 setup.py --auto-updates to get just this question on an existing install. To undo it, delete /etc/apt/apt.conf.d/20auto-upgrades and /etc/apt/apt.conf.d/52rwsols-auto-updates. The log is /var/log/unattended-upgrades/unattended-upgrades.log. Packages that did not come from apt (certbot is installed as a snap, which updates itself) are not covered.
  • Use a strong passphrase, and prefer HTTPS everywhere you can.

Clone this wiki locally