ReferenceEvery page

panel-relay(8)

the relay panels connect out to

Name

panel-relay — the relay panels connect out to

Synopsis

panel-relay [-f file] [serve]

panel-relay [-f file] code [group]

panel-relay [-f file] list [group]

panel-relay [-f file] remove name

panel-relay [-f file] outside off|on name

panel-relay [-f file] group add id [title ...]

panel-relay [-f file] group list

panel-relay [-f file] group remove id [--yes]

panel-relay [-f file] domain add|remove domain

panel-relay [-f file] domain list

panel-relay version

Description

panel-relay runs on a VPS, not on a panel. Panels connect out to it, so nothing is opened at home, and it passes on connections it cannot read:

From outside: a browser asking for a panel's name reaches that panel, if the panel's From outside is switched on. The relay reads only the name the browser asked for; the connection stays encrypted between the browser and the panel, with the panel's own certificate.
Between sites: a panel asks the relay for another panel by name, and the two speak their own fleet connection through it, each checking the other's key.

One relay serves any number of panels, kept apart in groups: one household's or customer's panels each. A panel sees and reaches only the panels of its own group; panels that joined before there were groups are in the group default.

A panel joins with a join code, made with code for a group, typed into the panel once (Maintenance, Relay). A second machine with the same key as a connected panel — a copied SD card — is refused, with what to remove on it. A panel is known to the relay by its key; its name is the one it has (Maintenance, Its name).

The relay's certificate is Let's Encrypt's, for its own name, by the DNS challenge through Cloudflare's API, renewed by itself 30 days before it ends. It points its own name at this machine at start, and a panel's name while that panel's From outside is on; it takes a panel's record away when that is switched off, or the panel leaves or is removed. A record already there saying something else is neither replaced nor taken away. Records are DNS only, never proxied by Cloudflare. A name's record is made with the token kept for the domain it is in (domain add), the longest such domain; a name in none, with the token in relay.conf.

A panel may ask it to drop an address that keeps failing to sign in, for that panel, for up to a day; it keeps such blocks in memory, and the panel tells it again when it connects. From any one address it lets through at most 120 new connections a minute, and 16 waiting at once.

Once its port is bound it confines itself with Landlock, where the kernel has it: it writes only its state directory, reads the system's certificates and the resolver's files, and keeps no capability.

Commands

serve: The relay itself, as systemd runs it. The default.
code [group]: A join code for one panel of the group, usable once within a day, printed as name/code, which is what the panel is given. Without a group, for default.
list [group]: The panels that joined, or one group's: NAME, GROUP, JOINED, NOW (connected or away, as the running relay last said; a question mark when it has not said so for two minutes), and OUTSIDE (on, off, or held).
remove name: A panel taken away, and its record; the relay drops it within half a minute.
outside off name: From outside switched off for the panel and held off: its record taken away, and the panel cannot switch it on again; its Relay row says so.
outside on name: The hold lifted: the panel may switch From outside on again. It is not switched on by this.
group add id [title ...]: A group: its id lower-case letters, digits and hyphens, up to 32; the title free text.
group list: The groups, with their panels and the codes waiting for them.
group remove id [--yes]: A group taken away with its panels and codes, and the records of those reached from outside. It asks first, unless --yes.
domain add domain: Asks for a Cloudflare token for the domain (Zone: Read and DNS: Edit on it), checks that it sees the domain's zone, and keeps it. Panels named in the domain are pointed with it from then on.
domain list: The domains with a token of their own.
domain remove domain: Its token forgotten.
version

Configuration

/etc/panel-relay/relay.conf, or the file given with -f: key = value lines.

name name: The relay's own name, in the Cloudflare zone, like relay.example.com. Required.
address ipv4: This machine's public IPv4 address, which the names are pointed at. Required.
address6 ipv6: And its IPv6 address, if it has one.
email address: Where Let's Encrypt writes if the certificate needs attention. Optional.
cloudflare_token_file path: A Cloudflare API token that may edit the zone's DNS. Default /etc/panel-relay/cloudflare.token.
state_dir path: The panels admitted, the join codes not used yet (as hashes), the certificate and the Let's Encrypt account. Default /var/lib/panel-relay.
listen address: Default :443.
acme_directory url, cloudflare_api url: For tests: the certificate authority and Cloudflare's API.

Files

/etc/panel-relay/relay.conf, /etc/panel-relay/cloudflare.token: root's, group panel-relay, 0640.
/var/lib/panel-relay/state.json: The groups, the panels and the codes.
/var/lib/panel-relay/now.json: Who is connected, as the running relay last said.
/var/lib/panel-relay/domains/domain.token: A domain's token, 0600, the relay's user's.
/var/lib/panel-relay/cert.pem, key.pem, account.key

Installing

On a Debian VPS, from panel-relay-version.tar.gz:

tar xzf panel-relay-1.151.0.tar.gz
cd panel-relay-1.151.0
sudo sh install.sh

It asks for the name, the address, an email and the token, writes the configuration, starts the relay under systemd as its own user with port 443 its one privilege, and prints the first join code. Run again to upgrade.

Examples

panel-relay group add smith "The Smiths"
panel-relay domain add smith.nl
panel-relay code smith
panel-relay list smith
panel-relay outside off home.smith.nl