Technical details & security

In short

• No port forwarding, no DynDNS. The Relay opens nothing to the internet; it makes every outside connection itself.
• Your pool controller’s credentials stay on the Relay. They are not sent to the cloud.
• End-to-end encrypted away from home. From app version 1.2 with an updated Relay, what the app exchanges with your Relay through the tunnel is encrypted between your phone and your Relay — the cloud only forwards data it can’t read.
• The PoolPilot Cloud runs at Hetzner in Germany — and the encrypted backups are in Germany too.
• Signed updates and open source code (MIT) — you don’t have to trust us blindly.

What the Relay runs on

Any always-on Linux with systemd on the same network as your pool controller. The installer detects the architecture by itself:

Not supported is 32-bit ARMv6 — that is, the original Raspberry Pi, the Pi Zero and the Pi Zero W. The installer stops there with a message. The Pi Zero 2 W, on the other hand, is a 64-bit device and works.

Home Assistant: as an app, the Relay needs Home Assistant OS or Supervised on a 64-bit system (aarch64 or amd64) — see Home Assistant.

The tunnel in plain words

At home everything runs over your Wi-Fi. Away from home it goes through the tunnel: a connection the Relay opens from your home to the PoolPilot Cloud and keeps open.

• Encrypted. The tunnel runs over TLS. Before the Relay logs in, it checks the tunnel server’s certificate against the one the PoolPilot Cloud gave it at pairing — so it doesn’t log in to an impostor.
• Only for paired phones. A request through the tunnel still needs the access key of a phone you paired. Without one, the Relay refuses it — knowing your Relay’s address is not enough. The same goes for your pool controller’s web interface. The one exception is a small public info page (such as the Relay’s version, its ID, whether it is paired, and its public fingerprint), which reveals nothing that would let anyone in.
• The sensitive things stay at home. Pairing, factory reset and resetting the household work only on your home network. Through the tunnel the Relay refuses them, even from a paired phone.
• End-to-end encrypted. Everything the app exchanges with your Relay through the tunnel — managing the Relay, your pool readings, and your pool controller’s own web interface in the app’s built-in browser — is encrypted end-to-end between your phone and your Relay. The Relay itself answers the encrypted connection, with the same certificate as on your home network, and the app only accepts the fingerprint it learned when you paired. The cloud forwards encrypted data it can’t read. The last hop, from the Relay to your pool controller on your home network, is unchanged and often plain HTTP, because that’s what many controllers speak.
• What the cloud still sees. That a connection to your controller’s address was made (the controller’s ID is part of that address), when, from which IP address (not logged for normal connections — see below), and how much data flowed. If a connection uses the older TLS 1.2, the cloud can also see the Relay’s certificate, which names the Relay’s ID and the device’s host name (as it was when the Relay first started). It doesn’t see what you request, your controller’s login or your readings.
• Separate from the tunnel. For pairing, your household and setting up push, the app talks to the PoolPilot Cloud directly, and the Relay sends your alerts to the cloud so it can deliver push messages (see What’s stored where). Those connections are encrypted too, but they end at the cloud.
• Older app versions. This applies from PoolPilot app version 1.2 with Relay 0.11 or newer. Older app versions still use the previous connection: the phone talks to the PoolPilot Cloud encrypted, and the cloud decrypts each request and passes it on, encrypted again, through the tunnel. Your requests and the controller’s answers are visible in the cloud only for that moment of forwarding — they are neither stored nor analysed. With app 1.2 and a Relay older than 0.11 there is no fallback to that connection: remote access through the Relay pauses until the Relay is updated, and at home everything keeps working.
• No traffic log. The tunnel’s web front end keeps no access log, so there’s no trail of what you did with your pool and when. The tunnel server only tells the cloud that a Relay connected, is still online or went offline — never what passes through — and the cloud keeps only the latest time of each, for the online status in the app. Only warnings and errors are logged — routine logins and traffic are not. A warning about a rejected or malformed connection can contain the IP address it came from; the logs are size-capped and rotate.

On your home network the app talks to the Relay encrypted as well and checks its certificate: at pairing the app learns the Relay’s fingerprint and from then on only trusts that one Relay.

Network and ports

On your home network

The Relay also talks to your pool controller on your home network — over HTTP or HTTPS, whichever the controller uses.

To the internet — outgoing only

Home routers normally allow outgoing connections — so there’s nothing to set up on your router.

What’s stored where

On the Relay

Everything the Relay needs to survive a restart lives in one file: /var/lib/poolpilot-relay/state.json (in Home Assistant /data/state.json). Its main contents:

• the Relay’s TLS identity — the fingerprint you see at pairing is derived from it,
• the paired phones with name and role — only a hash of their access keys, never the key itself,
• your pool controllers with address, name and type — and their username and password,
• your alert rules, plus a short queue of alerts not yet delivered,
• the credentials for the tunnel,
• settings such as the update toggle and the poll interval.

Next to it are the config file /etc/poolpilot-relay/config and the logs in the systemd journal.

In the PoolPilot Cloud

The cloud knows the Relay and the household it belongs to, your pool controllers’ type, address and name, and the tunnel credentials it issued. It receives your alerts (which rule fired, the value, the pool’s name) so it can send them as push messages, and keeps them for up to 30 days so you can re-read them in the app. The Relay does not upload your regular readings.

The PoolPilot Cloud runs at Hetzner in Germany, and its encrypted backups are in Germany too. Exactly what is processed there, for what and for how long, is spelled out in the Privacy Policy.

Signed releases and updates

Every version is published on GitHub Releases with a list of SHA-256 checksums, signed with minisign.

• The installer checks the checksum of every download and stops on a mismatch. When minisign is installed (the installer offers to install it), it also checks the signature.
• Self-update always checks the signature — against a key built into the Relay — and then each file’s checksum. The download address is built in too, so not even the PoolPilot Cloud can point the Relay at another server. More under Updates & settings.
• The installer runs as your normal user and shows you the sudo steps before it asks for your password. It sets up no telemetry, no cron jobs and no changes to your shell profile. You can read it first in the repository: deploy/relay/install.sh.

Check a download yourself

Fetch sha256sums.txt and sha256sums.txt.minisig from the same release and the public key deploy/relay/minisign.pub from the repository, then:

minisign -Vm sha256sums.txt -p minisign.pub   # the signature
sha256sum -c --ignore-missing sha256sums.txt  # the files you downloaded

Open source

The Relay is open source under the MIT licence. For the tunnel it includes frp, which is under the Apache 2.0 licence (see NOTICE in the repository). You’ll find the full source code on GitHub.