vitalygashkov/rucens/amnezia-vps-setup

Configure AmneziaWG on a VPS

Deliver a working .conf for each device on the server the user identified. Commands assume Ubuntu/Debian with systemd, root privileges, and Bash. This is a native installation using awg-quick, without Docker or a control panel. The Ubuntu PPA instructions do not apply to Debian. Replace angle-bracket placeholders before running examples, and stop on failed installation or configuration commands.

Collect missing inputs

Do not ask again for information the user has already provided. If missing, ask for:

• VPS IP or hostname, OS, SSH user, and authentication method;
• the apps and devices that will connect;
• the number of independent profiles needed;
• whether to tunnel all traffic or only selected networks;
• whether the VPS has public IPv6;
• a preferred UDP port, if the user has one.

Assume the user's Keenetic or Netcraze supports the classic wireguard asc parameters. Do not ask for the router model, firmware version, or LAN subnet as setup prerequisites. The user is responsible for reporting unsupported hardware or firmware and unusual LAN addressing. Revisit these details only if the user reports a relevant limitation or troubleshooting reveals a concrete compatibility or subnet conflict.

Choose the protocol version

Select the protocol from the stated client types and the defaults below without requiring a router compatibility questionnaire.

• For the official AmneziaWG app, use a current supported version.
• If clients include Keenetic/Netcraze with the wireguard asc CLI command, default to a compatible AWG 2.x setup with Jc Jmin Jmax S1 S2 H1 H2 H3 H4 parameters.
• Keep router setups on the classic compatible profile unless the user explicitly requests a newer protocol and supplies its compatibility details.

All clients on one server must use compatible protocol parameters. S1, S2, and H1...H4 must match the server. Jc, Jmin, and Jmax may technically differ, but matching values are easier to check and maintain.

Scope and safety

• Before making changes, tell the user which server and services the work will affect.
• Do not put SSH passwords in command arguments, shell history, URLs, or client files.
• Do not print private keys or preshared keys in diagnostic output.
• Do not reuse keys or obfuscation parameters from another server.
• Do not replace the entire existing firewall ruleset.
• Do not enable UFW blindly. Allow SSH first to avoid losing access.
• Do not run full-upgrade, change the kernel, or reboot the VPS without a need and the user's agreement.
• Inspect existing VPNs and Docker networking before changes. Preserve their services, routes, and firewall rules. VLESS on TCP 443 can coexist with AWG on UDP; check actual listeners, interface names, and subnets.
• Do not install a third-party one-click script when official components can do the same job.
• Create a separate key pair for each device. Sharing one profile between active devices causes endpoint changes and unstable connections.
• The client private key must remain only with the user. Delete the temporary client copy from the VPS after delivery.
• After setup, suggest switching to SSH keys and changing the root password if the password was shared in the conversation.

1. Inventory the server

Connect over SSH and collect the initial state without making changes:

uname -a
. /etc/os-release && printf '%s %s\n' "$PRETTY_NAME" "$VERSION_CODENAME"
dpkg --print-architecture 2>/dev/null || uname -m
ip -brief address
ip route show default
ss -lntup
df -h /
free -h
timedatectl status
command -v awg || true
command -v amneziawg-go || true
command -v docker || true
systemctl status awg-quick@awg0 --no-pager 2>/dev/null || true
ufw status verbose 2>/dev/null || true
nft list ruleset 2>/dev/null || true
iptables -S 2>/dev/null || true

Identify and record:

• the VPS's public address;
• the external interface from the default route, such as ens3;
• kernel version;
• architecture;
• an available UDP port;
• the active firewall system;
• whether public IPv6 is available.

If AmneziaWG already exists, inspect its service and configuration without printing keys. When adding clients, reuse its server keys and protocol parameters, allocate unused client addresses, and append peers. Skip installation and server key regeneration; generate fresh client keys and a preshared key for each new peer. Do not overwrite an occupied interface or configuration with the fresh-install template.

Before editing an existing configuration, back it up and retain the path for rollback:

config=/etc/amnezia/amneziawg/awg0.conf
backup=$(mktemp "${config}.bak.XXXXXX")
cp -p -- "$config" "$backup"
chmod 600 "$backup"

If a change prevents startup, restore with cp -p -- "$backup" "$config", restart the existing service, and check its status. Back up any firewall file separately before editing it.

2. Choose a kernel module or userspace

AmneziaWG can use a kernel module or the official amneziawg-go userspace implementation.

Before installation, check the current official sources:

• AmneziaWG kernel module;
• official `awg` and `awg-quick` tools;
• `amneziawg-go` userspace implementation;
• AmneziaWG parameter constraints;
• official Amnezia self-hosted server instructions.

Prefer the kernel module when the official package explicitly supports the OS version and running kernel. It is faster and uses less CPU.

Use amneziawg-go when:

• DKMS fails to build against the running kernel;
• the VPS does not allow loading modules;
• no compatible package exists for the distribution;
• installing the module would require a questionable kernel downgrade.

3. Install the official package

If the exact Ubuntu version and kernel are supported, follow the official repository's current instructions. A typical installation looks like this:

export DEBIAN_FRONTEND=noninteractive
apt-get update
apt-get install -y --no-install-recommends \
  software-properties-common python3-launchpadlib gnupg2 \
  "linux-headers-$(uname -r)"
 
add-apt-repository -y ppa:amnezia/ppa
apt-get update
apt-get install -y amneziawg

Check the result:

dkms status
modprobe amneziawg
lsmod | grep amneziawg
awg --version
awg-quick --help

If DKMS fails, read the build log. Do not reboot hoping the error will disappear. Switch to userspace if the problem is kernel incompatibility.

4. Install the userspace implementation

Select compatible tags from the official repositories and record their exact versions and commit IDs. Check protocol support and the selected tag's go.mod requirements against go version. Do not upgrade to a new protocol merely because its tag is newer. Prefer a compatible official package or release binary when available; otherwise build from source. Do not overwrite an existing source checkout or uninstall shared build dependencies afterward.

For Ubuntu/Debian:

export DEBIAN_FRONTEND=noninteractive
apt-get update
apt-get install -y --no-install-recommends \
  ca-certificates git make gcc libc6-dev golang-go iptables iproute2
 
install -d -m 0755 /usr/local/src
cd /usr/local/src
 
git clone --depth 1 --branch '<AWG_GO_TAG>' \
  https://github.com/amnezia-vpn/amneziawg-go.git
 
git clone --depth 1 --branch '<AWG_TOOLS_TAG>' \
  https://github.com/amnezia-vpn/amneziawg-tools.git
 
cd /usr/local/src/amneziawg-go
make
install -m 0755 amneziawg-go /usr/local/bin/amneziawg-go
 
cd /usr/local/src/amneziawg-tools/src
make
make install WITH_SYSTEMDUNITS=yes

Check the versions and awg-quick fallback:

/usr/local/bin/amneziawg-go --version
/usr/bin/awg --version
grep -n 'amneziawg-go' /usr/bin/awg-quick
systemctl cat awg-quick@.service

An Unknown device type message is expected in userspace mode if awg-quick then reports fallback and successfully starts amneziawg-go. An inactive service or missing interface indicates failure; that message alone does not.

5. Choose the port and subnet

Use an available UDP port that the client network and provider permit, for example 585/udp.

Do not use a port that is already occupied:

ss -lunp

For a personal server, use a dedicated private subnet, for example:

10.8.1.0/24
server: 10.8.1.1
first client: 10.8.1.2

Check for overlaps with routes and VPNs visible on the VPS and any networks the user has already mentioned. Otherwise assume the home LAN does not overlap; do not request its subnet or require confirmation. Choose another RFC1918 subnet if a known overlap exists.

6. Obfuscation parameters

For the classic nine-parameter router-compatible profile below, use these conservative limits. Verify support against the selected component versions; newer protocol features need matching client support:

• Jc: 1 to 128, with a practical range of 4 to 12;
• Jmin < Jmax;
• Jmax must be below the external path MTU to avoid fragmentation; the small values generated below also fit MTU 1280;
• S1 <= 1132 at MTU 1280;
• S2 <= 1188 at MTU 1280;
• S1 + 56 must not equal S2;
• H1...H4 must be distinct numbers from 5 to 2147483647.

Generate a fresh set for each server. Example Bash generation within these limits:

jc=$((4 + RANDOM % 9))
jmin=$((8 + RANDOM % 33))
jmax=$((jmin + 20 + RANDOM % 61))
s1=$((15 + RANDOM % 136))
 
while :; do
  s2=$((15 + RANDOM % 136))
  [ "$s2" -ne "$((s1 + 56))" ] && break
done
 
random_h() {
  local random_u32
  random_u32=$(od -An -N4 -tu4 /dev/urandom)
  printf '%s\n' "$((5 + random_u32 % 2147483642))"
}
 
h1=$(random_h)
h2=$(random_h)
h3=$(random_h)
h4=$(random_h)
 
while [ "$h2" = "$h1" ]; do h2=$(random_h); done
while [ "$h3" = "$h1" ] || [ "$h3" = "$h2" ]; do h3=$(random_h); done
while [ "$h4" = "$h1" ] || [ "$h4" = "$h2" ] || [ "$h4" = "$h3" ]; do
  h4=$(random_h)
done

Do not print these variables alongside keys in a general log. ASC numbers themselves are not secrets, but the completed client profile contains secrets.

7. Client and server keys

Generate keys with the installed awg:

set +x
umask 077
 
server_private=$(awg genkey)
server_public=$(printf '%s' "$server_private" | awg pubkey)
 
client_private=$(awg genkey)
client_public=$(printf '%s' "$client_private" | awg pubkey)
 
preshared_key=$(awg genpsk)

Capture these values in a private shell session without tracing or printing them. After writing the configurations, run unset server_private server_public client_private client_public preshared_key.

For the next device, create a new client key pair and assign a new address, such as 10.8.1.3/32. Keep the server key and obfuscation parameters unchanged.

8. Server configuration

The official awg-quick looks for its configuration here:

/etc/amnezia/amneziawg/awg0.conf

Create the directory before writing the file, with umask 077 still active:

install -d -m 0700 /etc/amnezia/amneziawg

Substitute the external interface, port, keys, and ASC parameters. The hooks below are for an unmanaged iptables ruleset with no earlier blocking rules. For UFW or a managed nftables ruleset, omit both hooks and configure forwarding and NAT through that firewall instead. Use one owner for these rules.