# Run a Fenris server

Last updated 19 Nov 2026 Applies to 0.1

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

1. Create a virtual machine: Ubuntu Server 24.04 LTS, the region nearest you, a small size (`Standard_B1s`, or `Standard_D2pls_v6` for Arm), SSH with a key.
2. 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.
3. SSH in and continue with [Install](#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](#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](#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 text` for ntfy);
- `--alert-email smtps://you@example.com@smtp.example.com --alert-email-to you@example.com --alert-email-password-file /etc/fenris/smtp-password` to 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-server` is the server. Back it up, sealed with a passphrase, with `sudo fenris-server backup --state /var/lib/fenris-server --out <file>`, and put it on another machine with `sudo fenris-server restore --state /var/lib/fenris-server --from <file>`, without enrolling your devices again.
- `root.key` in 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 to `fenris-server rotate --root <file>` at least every 90 days.

**On this page** [What it needs](#what-it-needs)[On Azure](#on-azure)[Elsewhere](#elsewhere)[Install](#install)[Domain mode](#domain-mode)[The admin console](#the-admin-console)[Alerts](#alerts)[Updates](#updates)[Keep it safe](#keep-it-safe)
