← All documentation

Everyday

Networking and VPN

How AOS connects, how WireGuard VPNs work on it, and how to set up a VPN of your own that AOS accepts.

Wired and Wi-Fi

Plug in a cable and AOS is online: every wired port uses DHCP. For Wi-Fi, open Settings → Network, pick a network and type the passphrase. WPA2 and WPA3 are supported.

Joining and forgetting networks changes the system, so it needs an administrator. Once a network is saved, every account on the machine uses it.

Enterprise Wi-Fi (eduroam, office networks) is under Settings → Network → Advanced. It supports PEAP (MSCHAPv2) and TTLS (PAP), with an optional CA certificate file.

Names are resolved by systemd-resolved. When a network doesn’t say which DNS server to use, AOS falls back to Quad9.

Nothing comes in

The firewall drops every incoming connection that isn’t a reply to something your machine started. The exceptions are DHCP, ping, ports an app declared and you switched on (Settings → Network → Advanced → Open ports), and SSH. SSH only listens when you turn on Remote login on the same page. It accepts keys, never passwords, and the bar shows SSH open while it is on.

VPN: how it works on AOS

AOS uses WireGuard, a modern VPN built into the Linux kernel. A WireGuard tunnel is described by one small text file, a .conf, which your VPN provider or your own server gives you.

A tunnel belongs to the machine, not to one account. Its file is kept at /etc/wireguard/<name>.conf, readable only by root. A tunnel that is switched on comes back by itself after every restart, until you switch it off.

Adding a tunnel

  1. Save the .conf file somewhere in your home, for example ~/Downloads/office.conf.
  2. Open Settings → Network, switch on Advanced, and go to VPN (WireGuard).
  3. Type the file’s path and press Import. The file name becomes the tunnel’s name, here office.
  4. Switch office connected on.

Every step except looking at the list needs an administrator’s password.

Full or split tunnel

Each tunnel has a switch: Send all traffic through the tunnel.

  • Off (split tunnel): only traffic for the VPN’s own networks goes through it, as listed in the file’s AllowedIPs. Everything else goes out directly. This suits a VPN to the office or your home network.
  • On (full tunnel): everything goes through the VPN. This suits a privacy VPN.

In full-tunnel mode there is one more switch, Reach the local networks directly. Your printer, NAS and other things at 192.168.x.x, 10.x.x.x and 172.16-31.x.x stay reachable while everything else goes through the tunnel.

Rules for the file

AOS accepts a standard WireGuard file, with a few rules for safety:

  • It must be inside your home, be a regular file, and end in .conf.
  • The name is 1 to 15 letters, digits, - or _.
  • It must have an [Interface] with a PrivateKey.
  • No PreUp, PostUp, PreDown or PostDown lines. Those run commands as root, so AOS refuses the file. Delete those lines first; the tunnel works without them.
  • A tunnel with the same name is never overwritten. Remove the old one first.

To change a tunnel, remove it and import the new file.

Your own VPN server

Nothing on the server needs to be AOS-specific: any standard WireGuard server works. On the server, add your AOS machine as a peer with its public key and its address, for example AllowedIPs = 10.8.0.2/32. Then give AOS a file like this:

[Interface]
PrivateKey = <this machine's private key>
Address = 10.8.0.2/32, fd08::2/128
DNS = 10.8.0.1

[Peer]
PublicKey = <the server's public key>
PresharedKey = <optional>
Endpoint = vpn.example.org:51820
AllowedIPs = 10.8.0.0/24, 192.168.50.0/24
PersistentKeepalive = 25

Tips:

  • List the server’s own networks in AllowedIPs (the VPN subnet and your home LAN, as above), not 0.0.0.0/0. Then the full/split switch works both ways. A file that already says 0.0.0.0/0 can only be a full tunnel.
  • Keep DNS a private address on the VPN, like 10.8.0.1. Then names resolve through the tunnel even when “reach the local networks” is on.
  • PersistentKeepalive = 25 keeps the tunnel alive behind home routers.
  • Supported fields: PrivateKey, Address, DNS, MTU, ListenPort, Table, FwMark in [Interface], and PublicKey, PresharedKey, AllowedIPs, Endpoint, PersistentKeepalive in [Peer].

What a VPN can see

  • Your VPN provider or server sees everything you send through the tunnel, as your internet provider otherwise would: which sites you connect to, and the content of anything not encrypted. Choose a provider you trust, or run your own.
  • Websites see the VPN server’s address instead of yours.
  • Your local network and your internet provider see that you are talking to the VPN server, and how much, but not what.
  • Apps on your machine don’t see the VPN at all: the tunnel is set up by the system, and a sandboxed app can’t change it.

An app that accepts connections over the VPN only, such as a game server for friends on the same tunnel, can declare VPN ports. AOS opens those only on WireGuard tunnels, and you switch them on in Open ports.

Not there yet

  • OpenVPN: the program is in the system, but there is no Settings page for .ovpn files yet, and no supported way to start one. Use WireGuard for now; most providers offer it.
  • Kill switch: if a tunnel drops, traffic is not blocked.
  • Per-app routing: the split is by network, not by app.
  • Mobile broadband has no Settings page yet.