Run a Fenris server
Your devices bond their links into one tunnel to a server you run. Any Linux VPS works; this guide sets one up on Azure first, then says what differs elsewhere.
What it needs
- Linux 5.15 or newer with systemd and nftables: Ubuntu 24.04 is a good choice. One vCPU and 1 GB of memory are enough for a household.
- A public IPv4 address, with UDP 443 open to everyone (and TCP 443 if devices will be on networks that block UDP).
- A public IPv6 address too, if you can: a device’s link with only IPv6, as some cellular modems and fibre lines have, reaches the server there. The server listens on both and tells devices its IPv6 address on its own; open UDP 443 for IPv6 as well. Without one, such links go through the network’s NAT64 where it has one.
- SSH from your own computer only.
On Azure
- Create a virtual machine: Ubuntu Server 24.04 LTS, the region nearest you,
a small size (
Standard_B1s, orStandard_D2pls_v6for Arm), SSH with a key. - In its network security group, allow inbound UDP 443 from any source, TCP 443 too if you want the fallback, and TCP 22 from your own address only.
- SSH in and continue with Install.
Elsewhere
Hetzner, Vultr, DigitalOcean, Oracle Cloud and the rest work the same way: make an Ubuntu 24.04 server and open UDP 443 (and TCP 443) in the provider’s firewall as well as on the server. Oracle Cloud’s images also block ports in their own iptables rules; allow 443 there too.
Install
Fenris is installed from a signed release. The installer checks every file it uses against Fenris’s release keys, which are built into it, before anything runs:
curl -fsSLO https://releases.fenris.network/<version>/install.sh sudo sh install.sh --from https://releases.fenris.network/<version>/ \ --address <public IP>:443 --admin <your name>
Add --tcp-fallback to take TLS over TCP on port 443 as well, and
--domain for domain mode.
The server answers your devices’ DNS itself, whatever resolver they ask,
through the one the server’s machine uses. Lookups then work from any network
and never leave a device outside the tunnel. To choose the resolver, encrypted
so the server’s network sees no names, add one: over TLS
--dns-upstream tls://1.1.1.1#cloudflare-dns.com, over HTTPS
--dns-upstream https://1.1.1.1/dns-query#cloudflare-dns.com, or over QUIC
--dns-upstream quic://94.140.14.14#dns.adguard-dns.com.
It installs the server and its systemd unit, makes the server’s keys, makes you the first admin and shows a QR code for an authenticator app (scan it: the admin console asks for its codes), and starts it. It also keeps the release it was installed from, so your devices can update from the server.
Last, it prints your first device’s invite link, with a QR code. Scan it with
the Fenris app, or paste the link into the app or fenris join, and check the
code the device shows matches the one printed. The link works once, for 24
hours.
To change these options later, run install.sh again with the ones you want:
the server keeps its keys and devices. Other options, such as
alerts, go in /etc/fenris/server.env, which the installer never
touches:
FENRIS_SERVER_FLAGS=--alert-webhook https://ntfy.sh/<topic> --alert-format text
then sudo systemctl restart fenris-server.
Domain mode
If the server has a domain name, it can get a certificate for it from Let’s Encrypt and show it on its TLS/TCP paths, so a network that blocks UDP sees an ordinary HTTPS site. Point the name’s A (and AAAA) record at the server, with no proxy in front (on Cloudflare: DNS only), open TCP 443, and install with:
--domain vpn.example.com
This turns on the TCP fallback too. The server proves the name to Let’s
Encrypt on TCP 443 itself (TLS-ALPN-01, no port 80), keeps the certificate’s
key in /var/lib/fenris-server/acme/ and renews it on its own, well before it
expires. Your devices learn the name and the key the next time they connect.
Change the name and the server orders a certificate for the new one as it
starts.
Invite links can then carry the name instead of an address:
fenris-server invite --address vpn.example.com, or the name in the
console’s invite form. A device looks it up as it joins; the server still
proves itself with the link’s code, so a wrong answer cannot pass for it.
The name is then visible to the networks your devices use, and in the public Certificate Transparency logs.
Whoever opens the name in a browser gets a closed connection. To show them a
site instead, put a static one (an index.html and its files, a 404.html
if you like) in a directory and add --decoy-dir <directory>. The installer
copies it to /var/lib/fenris-decoy, where the server reads it once at start
and serves it over HTTP/2 or HTTP/1.1; run the installer again to change it.
Your devices then also find the admin console under the name, through their
tunnels, at https://vpn.example.com/admin, with no certificate warning.
There you can add passkeys (Settings, Passkeys) and sign in with them instead
of codes.
The admin console
The console is never open to the internet: only your devices reach it,
through their tunnels. On a device that has joined, open
https://vpn.example.com/admin in domain mode, or https://10.77.0.1/admin
otherwise, and sign in with your name and a code from the app. Without a
domain the browser warns about the console’s certificate: compare its SHA-256
with journalctl -u fenris-server | grep 'admin console' on the server
before you go on.
Without a device that has joined, reach it through SSH from your computer:
ssh -L 8443:127.0.0.1:8443 <you>@<server>
then open https://127.0.0.1:8443/admin, and check the certificate the same
way.
From the console you add devices (each gets a one-time invite link), see them and their links, revoke them, forward ports and read the audit log. The same on the command line:
sudo fenris-server invite --state /var/lib/fenris-server --address <public IP>:443 sudo fenris-server devices --state /var/lib/fenris-server sudo fenris-server revoke --state /var/lib/fenris-server --device <id>
If the server has a public IPv6 address too, give it with a second
--address (such as [2001:db8::7]:443): a device that cannot reach the
first address joins through the other.
Alerts
The server raises an alert when a device has been offline, or short of a
link, for five minutes (--alert-after), or when it runs short of disk or
CPU, and resolves it when that ends. The console lists them. To be told as
they happen, add to FENRIS_SERVER_FLAGS in /etc/fenris/server.env:
--alert-webhook https://…to post each to a chat tool or ntfy (--alert-format textfor ntfy);--alert-email smtps://you@example.com@smtp.example.com --alert-email-to you@example.com --alert-email-password-file /etc/fenris/smtp-passwordto email each, always encrypted (smtp://uses STARTTLS on port 587).
Updates
sudo fenris-server release fetch --state /var/lib/fenris-server
fetches the latest release, checks its signatures and every file, and keeps it. The server then installs its own new version at a quiet moment, and your devices update from the server through their tunnels, each when it is quiet. Nothing else contacts Fenris: devices only ever talk to your server.
sudo fenris-server release show --state /var/lib/fenris-server says which
release the server holds.
Keep it safe
/var/lib/fenris-serveris the server. Back it up, sealed with a passphrase, withsudo fenris-server backup --state /var/lib/fenris-server --out <file>, and put it on another machine withsudo fenris-server restore --state /var/lib/fenris-server --from <file>, without enrolling your devices again.root.keyin it certifies the keys the server presents. To keep it off the server,fenris-server root export --state … --to <file> --remove; the server then reminds you tofenris-server rotate --root <file>at least every 90 days.