VPN and Linux: Set Up AmneziaWG on Ubuntu and Debian

VPN and Linux: choosing a VPN client

An AmneziaWG profile looks much like a WireGuard one, but it carries extra parameters that change how handshake and service packets look on the wire. Several of them must match the server, so you need a client that understands the AmneziaWG format.

Flex-VPN also offers VLESS + Reality profiles, but those are set up in Happ on Windows, macOS, Android and iOS. On Linux, the supported option is AmneziaWG, and it is the only protocol this guide covers. Use one client per machine: the app and awg-quick both manage routes and DNS, and running them side by side gives confusing results.

Installing Amnezia VPN on Ubuntu and Debian

For most desktop users the app is the simplest Linux VPN setup, because you never edit a config file. It runs as an ordinary user program and talks to a background service that has the rights to create the tunnel interface and change routes.

1. Check your architecture with uname -m. The official Linux build targets x86_64; on other hardware, use the terminal route below.
2. Download the Linux installer from the official Amnezia website or the amnezia-client releases page on GitHub, not from mirrors or re-uploads. If it comes inside an archive, unpack it first.
3. Make the installer executable with chmod +x followed by its file name, then start it with ./ in front of the name. It installs a system service, so expect a password prompt; if the release notes for your version say to run it with sudo, do that.
4. Open Amnezia VPN from your applications menu. If it does not appear, log out and back in so the desktop picks up the new launcher.

On Debian with a desktop environment, the same installer normally works. If the installer or the app stops with an error about the Qt xcb platform plugin, an X11 library is missing. The message usually names it; with current Qt versions it is often libxcb-cursor0, which you can add with sudo apt install libxcb-cursor0 before trying again.

Importing your AmneziaWG key

Flex-VPN keys are issued in the Telegram bot @vpn_flex_bot. Create a separate key for this computer instead of reusing the one from your phone: the base plan covers three devices (details on the pricing page), and one key per device lets you replace the key on one machine without touching the others.

1. Copy the whole key and check that pasting adds no spaces or line breaks, even if it wraps across lines in the chat.
2. In Amnezia VPN, choose the option to add a connection and paste the key. If you received a file instead, use the file import option. Button labels differ between app versions.
3. Confirm the import, select the new connection and connect.
4. Verify: a new tunnel interface should appear in ip link, and an IP-check page should now show the server's address instead of your own.

For screenshots of each step, see the Amnezia VPN and AmneziaWG setup guide. Amnezia VPN also runs on Windows, macOS, Android and iOS; give every device its own key.

Terminal route: amneziawg-tools and awg-quick

If you run Ubuntu Server or a minimal install, or simply want a VPN client on Linux that you can script, the amneziawg packages give you awg and awg-quick, the counterparts of wg and wg-quick, plus a kernel module built through DKMS.

Install the module and tools on Ubuntu

1. Enable source repositories, as the project's instructions require. On Ubuntu 24.04 and newer, add deb-src to the Types: line in /etc/apt/sources.list.d/ubuntu.sources; older releases use deb-src lines in /etc/apt/sources.list. Then run sudo apt update.
2. Install the prerequisites: sudo apt install -y software-properties-common python3-launchpadlib gnupg2 linux-headers-$(uname -r)
3. Add the official repository: sudo add-apt-repository ppa:amnezia/ppa
4. Install the package: sudo apt-get install -y amneziawg
5. Load and check the module: sudo modprobe amneziawg, then lsmod | grep amneziawg.

On Debian, the README of the amneziawg-linux-kernel-module project on GitHub describes adding the same Launchpad repository by hand: a signing key plus a sources entry. Follow the current README, and store the key in a keyring file referenced with signed-by, since apt-key is deprecated.

Bring the tunnel up

awg-quick reads the familiar [Interface] and [Peer] format described in our guide to WireGuard config files, plus AmneziaWG fields such as Jc, Jmin, Jmax, S1, S2 and H1–H4. It needs the profile as a .conf file. If you only have a text key meant for the app, ask support whether your profile can be provided as a config file, or use the desktop app instead.

1. Save the profile as /etc/amnezia/amneziawg/awg0.conf. The file name becomes the interface name, so keep it short: up to 15 characters, using letters, digits and a few symbols such as - and _.
2. Restrict access, because the file holds your private key: sudo chmod 600 /etc/amnezia/amneziawg/awg0.conf
3. Start the tunnel with sudo awg-quick up awg0 and stop it with sudo awg-quick down awg0.
4. Run sudo awg show. A recent latest-handshake time and growing transfer counters mean the tunnel is passing traffic.

If the kernel module cannot be loaded, awg-quick falls back to the userspace implementation, amneziawg-go, provided it is installed. That works where you cannot build modules, at some cost in CPU use.

DNS with systemd-resolved: avoiding leaks

A tunnel that carries all traffic while name lookups still go to your router's resolver is a classic DNS leak. How awg-quick applies DNS depends on your resolver. Ubuntu runs systemd-resolved by default; a standard Debian install usually does not. If /etc/resolv.conf points to 127.0.0.53, systemd-resolved is in charge.

When the profile contains a DNS = line, awg-quick passes those servers to the resolvconf command in exclusive mode. Under systemd-resolved, that becomes a catch-all routing domain on the tunnel interface, so every lookup goes through the tunnel.

If awg-quick stops with resolvconf: command not found, that command is missing. With systemd-resolved, the tidy fix is a symlink, because resolvectl acts as resolvconf when called by that name: sudo ln -s /usr/bin/resolvectl /usr/local/sbin/resolvconf. Adding a separate resolvconf package on such a system can leave two tools competing for /etc/resolv.conf. On Debian without systemd-resolved, install a resolvconf implementation such as openresolv.

• resolvectl status awg0 should list the DNS server from your profile and the ~. routing domain.
• resolvectl query example.com shows which link answered the lookup; with the tunnel up, it should be awg0.
• If AllowedIPs contains only 0.0.0.0/0 and your network has IPv6, IPv6 connections go outside the tunnel. Check the profile, or ask support which setting fits it.

For browser-based checks, see our article on DNS and VPN leaks. The desktop app applies DNS itself, but with systemd-resolved the same resolvectl checks work for it too.

Autostart and resume after sleep

Desktop app

Amnezia VPN has options to launch at login and to connect automatically. Their names vary between versions, but both live in the app's own settings, not in your desktop's startup tool.

awg-quick with systemd

The package ships a template unit, so sudo systemctl enable --now awg-quick@awg0 starts the tunnel now and on every boot. Check it with systemctl status awg-quick@awg0. Keep the headers metapackage for your kernel flavor installed (for example, linux-headers-generic on Ubuntu or linux-headers-amd64 on 64-bit Debian) so DKMS can rebuild the module for each new kernel; otherwise the tunnel can fail after the next reboot.

After suspend or a network change

AmneziaWG, like WireGuard, has no session to re-establish: when traffic resumes, a new handshake follows within seconds. If the profile includes PersistentKeepalive, it also keeps the NAT mapping on your router alive while the link is idle. If the tunnel stays silent after resume, sudo systemctl restart awg-quick@awg0 usually fixes it, and a script in /usr/lib/systemd/system-sleep/ can run that restart automatically. For recurring drops, work through why a VPN keeps disconnecting.

awg-quick has no built-in kill switch: if the tunnel stops or fails to come up, traffic uses your normal connection. For fail-closed behavior, add firewall rules through PostUp and PreDown, following the example in the wg-quick manual page, and test them before relying on them.

Troubleshooting: ip route, awg show and logs

When a Linux VPN setup fails, work from the bottom up: is the module loaded, does the handshake complete, does routing send traffic into the tunnel, and does DNS follow it?

To confirm routing, run ip route get 1.1.1.1. With a full tunnel up, the answer should mention dev awg0 and a separate routing table (51820 unless that number is taken). ip rule show should list a not fwmark rule and a suppress_prefixlength 0 rule: the first sends everything except the tunnel's own encrypted packets to that table, and the second keeps more specific routes, such as your local network, working. journalctl -u awg-quick@awg0 -b shows what the unit has done since boot. The desktop app has its own logging option in settings, useful if you contact support.