AmneziaWG Installer

September 6, 2026 · View on GitHub

Set up an AmneziaWG obfuscated VPN on any supported Linux server in under 2 minutes — with backward-compatible AWG 2.0 defaults, optional AWG 3.0 support, an optional web panel, and an optional traffic-obfuscation proxy (AmneziaWG 2.0 only).

VPN install → (optional) Web panel → (optional) Obfuscation proxy → Manage clients

📖 Background

This project started as a fork of RomikB/amneziawg-install. I needed a reliable way to stand up AmneziaWG 2.0 servers for testing WireSock Secure Connect, and the upstream script predated the 2.0 release — so I took it and extended it to generate and manage the new 2.0 obfuscation parameters (S3/S4 padding and the H1–H4 header ranges). It now also supports an explicit, capability-checked migration to AmneziaWG 3.0 while preserving AWG 2.0 as the default for new and existing installations.

Once the installer was solid, it was hard to stop:

  1. amneziawg-install.sh — the original script, extended for AmneziaWG 2.0 (S3/S4, H1–H4, migration from pre-2.0 installs), optional AmneziaWG 3.0 header protection, and optional AmneziaWG 3.1 (RandomTrailers / DisableCookies).
  2. amneziawg-web.sh — a web panel for managing clients and explicit AWG 2.0 / 3.0 / 3.1 migrations without touching the CLI.
  3. amneziawg-proxy.sh — a UDP obfuscation proxy that takes traffic camouflage to the next level: it wraps AmneziaWG (AWG 2.0 only) so the datagrams on the wire look like a legitimate QUIC, DNS, STUN, or SIP service to Deep Packet Inspection (DPI).

⚠️ amneziawg-proxy is compatible only with AmneziaWG 2.0 and is most powerful with WireSock Secure Connect 3.5+. The proxy is compatible only with AmneziaWG 2.0 (it is not compatible with AWG 3.0+ because AWG 3.0 uses S1–S4 padding as key material for header encryption). The proxy's full protocol-imitation feature set — coordinated client/server cover traffic, junk-packet shaping, and per-protocol padding — is only fully unleashed when paired with WireSock Secure Connect 3.5 or later on the client side. Standard AmneziaWG clients still connect through the proxy and benefit from the server-side obfuscation, but the bidirectional imitation requires the WireSock client.

🚀 Quick Start

VPN only (required):

curl -O https://raw.githubusercontent.com/wiresock/amneziawg-install/main/amneziawg-install.sh
chmod +x amneziawg-install.sh
sudo ./amneziawg-install.sh

Add the web panel (optional):

curl -O https://raw.githubusercontent.com/wiresock/amneziawg-install/main/amneziawg-web.sh
chmod +x amneziawg-web.sh
sudo ./amneziawg-web.sh install

Note: The web panel installer requires git to bootstrap the repository when run standalone. If git is not available, clone the repository manually or use --binary-src with a pre-built binary.

Add the obfuscation proxy (optional):

curl -O https://raw.githubusercontent.com/wiresock/amneziawg-install/main/amneziawg-proxy.sh
chmod +x amneziawg-proxy.sh
sudo ./amneziawg-proxy.sh

Makes the VPN traffic look like QUIC/DNS/STUN/SIP to DPI. Compatible with AmneziaWG 2.0 only (not compatible with AWG 3.0+). See Traffic Obfuscation Proxy.

✅ After installation:

  • VPN server is running
  • AWG 2.0 remains active by default; AWG 3.0 is enabled only by an explicit migration after userspace and kernel capability checks pass (do not enable AWG 3.0 if using amneziawg-proxy)
  • A client config file is generated at ~/awg0-client-<name>.conf
  • (If installed) Web panel listens on 127.0.0.1:8080 by default — access it on the server at http://127.0.0.1:8080, or change AWG_WEB_LISTEN / use a reverse proxy for remote access

🧠 How It Works

  • amneziawg-install.sh — required. Installs the VPN server, generates obfuscation parameters, creates client configs, and can transactionally enable AWG 3.0 after capability checks or return the installation to AWG 2.0.
  • amneziawg-web.sh — optional. Unified script for:
    • install — install the web panel
    • upgrade — upgrade the binary
    • uninstall — remove the panel
    • status — show installation status
  • amneziawg-proxy.sh — optional. Installs and manages the UDP obfuscation proxy that fronts AmneziaWG (AWG 2.0 only) and makes the traffic look like QUIC, DNS, STUN, or SIP. See Traffic Obfuscation Proxy below.

🤔 Choose Your Setup

GoalWhat to run
VPN server onlyamneziawg-install.sh
VPN + web panelamneziawg-install.sh then amneziawg-web.sh install
VPN + DPI-resistant obfuscationamneziawg-install.sh then amneziawg-proxy.sh (AWG 2.0 only)
Everythingamneziawg-install.sh, then amneziawg-web.sh install, then amneziawg-proxy.sh (AWG 2.0 only)
Advanced / developmentClone the repo, then run the scripts from the checkout

Most users should start here.

  1. Update your system and reboot before installing.
  2. Run the commands from Quick Start.
  3. Answer the prompts. The script installs AmneziaWG, configures the server, and generates a client config file.
  4. Run the script again at any time to add or remove clients.

🟡 Advanced Setup — VPN + Web Panel

⚠️ Requires VPN to be installed first (amneziawg-install.sh).

Use the Quick Start commands above, or clone the repository (best for teams or repeated upgrades):

git clone https://github.com/wiresock/amneziawg-install.git
cd amneziawg-install
sudo ./amneziawg-install.sh
sudo ./amneziawg-web.sh install

The installer automatically downloads required files and builds the panel. Add --install-rust if Rust is not already installed on the server.

See amneziawg-web/docs/INSTALL.md for all installer options.

🎭 Traffic Obfuscation Proxy (amneziawg-proxy)

⚠️ Requires VPN to be installed first (amneziawg-install.sh).

Important

Compatibility: AmneziaWG 2.0 only (incompatible with AWG 3.0+)

amneziawg-proxy is compatible only with AmneziaWG 2.0 and cannot be used when AWG 3.0 mode is enabled.

In AmneziaWG 2.0, the S1–S4 padding prefix consists of arbitrary random bytes that the proxy safely replaces with cover-protocol filler bytes (QUIC, DNS, STUN, or SIP headers) while preserving the encrypted payload. Starting with AmneziaWG 3.0, the S1–S4 padding values are used as key material for header encryption (HeaderProtectionKey). Modifying or rewriting them in flight breaks header decryption on the peer, and the encrypted headers prevent the proxy from classifying packets.

If you plan to use amneziawg-proxy, keep your interface in AWG 2.0 mode (the default). Do not enable AWG 3.0 on a proxied interface.

amneziawg-proxy is an async UDP proxy (written in Rust) that sits in front of your AmneziaWG server and disguises the traffic so that, to Deep Packet Inspection (DPI), the port appears to host an ordinary QUIC, DNS, STUN, or SIP service. AmneziaWG's own obfuscation already hides the WireGuard fingerprint; the proxy adds a second layer that makes the packets positively resemble a known, allowed protocol instead of merely looking random.

💡 Best paired with WireSock Secure Connect 3.5+. The proxy obfuscates the server → client direction on its own. Bidirectional imitation — where the client → server direction is camouflaged too — requires WireSock Secure Connect 3.5 or later, which implements the matching client-side protocol imitation and junk-packet shaping.

Install

The proxy installer detects the AWG interface, rebinds AmneziaWG to loopback, builds the binary, and installs a systemd service. One command does it all:

curl -O https://raw.githubusercontent.com/wiresock/amneziawg-install/main/amneziawg-proxy.sh
chmod +x amneziawg-proxy.sh
sudo ./amneziawg-proxy.sh

Run with no arguments and it walks you through guided prompts. Run it again later and it shows a management menu (status, logs, reconfigure, uninstall).

Non-interactive examples. amneziawg-proxy.sh forwards any flags to the installer (cloning the helper scripts on the fly when run standalone), so the one downloaded file is all you need:

# QUIC imitation (safest default) — public :51820 → loopback :51821
sudo ./amneziawg-proxy.sh \
  --non-interactive --listen-port 51820 --protocol quic

# DNS imitation that also answers real DNS queries (run on port 53)
sudo ./amneziawg-proxy.sh \
  --non-interactive --listen-port 53 --protocol dns \
  --dns-forward --dns-upstream 1.1.1.1:53

# STUN imitation (port 3478, WebRTC/NAT-permissive networks)
sudo ./amneziawg-proxy.sh \
  --non-interactive --listen-port 3478 --protocol stun

Full option reference, configuration keys, and troubleshooting live in amneziawg-proxy/doc/USAGE.md. Internal design and packet-level walkthroughs are in amneziawg-proxy/doc/ARCHITECTURE.md.

How It Works

After install, all client traffic flows through the proxy, which AmneziaWG no longer exposes directly:

                         ┌───────────────────────────────────┐
 VPN client ──── UDP ───►│  0.0.0.0:51820   amneziawg-proxy  │
 (DPI sees QUIC/DNS/     │            │                      │
  STUN/SIP)              │            ▼                      │
                         │  127.0.0.1:51821  awg0 (AmneziaWG)│
                         └───────────────────────────────────┘

The proxy does two complementary things:

  1. Probe response. When a scanner or DPI box sends a protocol probe (a QUIC Initial, a DNS query, a STUN Binding Request, a SIP request), the proxy replies with a valid protocol response — a QUIC Version Negotiation, a DNS answer, a STUN Binding Success, a SIP 100 Trying. The port therefore behaves exactly like the service it is pretending to be when actively probed.
  2. Padding transformation. Every outgoing AmneziaWG 2.0 packet already carries a random S1–S4 padding prefix. The proxy overwrites that prefix with protocol-conformant bytes (a QUIC short header, a DNS/STUN header, SIP header text) so the leading bytes and byte-distribution of each datagram match the imitated protocol — while the encrypted WireGuard payload that follows is left untouched. (Note: this relies on AmneziaWG 2.0 protocol semantics where headers are plaintext and S1–S4 padding is unkeyed; in AWG 3.0+, S1–S4 padding serves as key material for header encryption, so rewriting it breaks compatibility).
ModeWhat DPI seesTypical portGood for
quicQUIC 1-RTT / Version Negotiation443QUIC/HTTP-3-heavy networks (safest default)
dnsDNS query/response (optionally real)53DNS-filtered networks
stunSTUN Binding traffic3478WebRTC / NAT-traversal-permissive networks
sipSIP signaling5060VoIP-permissive networks
autoWhatever the client probes for—Mixed-probe environments

Traffic Examples

STUN mode — an outgoing server packet on the wire. The padding prefix is rewritten as a well-formed STUN message; a packet-capture tool dissects it as STUN and leaves the encrypted AmneziaWG payload as trailing bytes:

01 01 00 1c 21 12 a4 42  4f 7a 1c …   ← STUN: Binding Success Response, msg length 0x1c, cookie 0x2112A442
00 20 00 08 00 01 …                    ← XOR-MAPPED-ADDRESS attribute (12 B)
80 22 00 0c …                          ← SOFTWARE attribute (16 B; fills the prefix) → 12 + 16 = 0x1c
… encrypted AmneziaWG payload …        ← opaque ciphertext (trails the message, not parsed)

QUIC mode — a probe and its response. A DPI box sends a QUIC Initial; the proxy answers with a valid Version Negotiation packet, swapping the connection IDs per RFC 9000:

→  c3 00000001 04 aabbccdd 00            QUIC Initial probe (DCID=AABBCCDD)
←  c3 00000000 00 04 aabbccdd 00000001   Version Negotiation (SCID echoes the DCID)

DNS mode — a query answered for real. With --dns-forward, a DNS probe is forwarded to the upstream resolver and the genuine answer is returned, so the port doubles as a working resolver while still tunneling VPN traffic.

To inspect it yourself, capture on the server's public port and open the capture in Wireshark — frames decode cleanly as the imitated protocol, with no "malformed" or WireGuard markers:

sudo tcpdump -i any -w awg-proxy.pcap udp port 51820

Manage / Uninstall

Re-running amneziawg-proxy.sh on an installed host opens a management menu (status, logs, reconfigure, uninstall) — the simplest path, and it works from the single downloaded file:

sudo ./amneziawg-proxy.sh

From a repository checkout you can also drive the uninstaller non-interactively (keeps config/data by default; add --restore-awg to rebind AWG to the public port):

sudo ./amneziawg-proxy/scripts/amneziawg-proxy-uninstall.sh --force

⚙️ After Installation

  • VPN client config is saved to ~/awg0-client-<name>.conf. Import it into any AmneziaWG client app.
  • Web panel listens on 127.0.0.1:8080 by default. Access it on the server at http://127.0.0.1:8080, or change AWG_WEB_LISTEN / use a reverse proxy for remote access.
  • Re-run sudo ./amneziawg-install.sh to add or remove VPN clients interactively.
  • Check the web panel status at any time: 
    ./amneziawg-web.sh status

    The status command does not require sudo.

🔄 Maintenance

All web panel lifecycle actions use the same script:

Upgrade the web panel:

sudo ./amneziawg-web.sh upgrade

Uninstall the web panel (keeps config and data):

sudo ./amneziawg-web.sh uninstall --force

Uninstall and purge all data:

sudo ./amneziawg-web.sh uninstall --purge-config --purge-data --force

The script works standalone — it automatically downloads required files when run.

⚡ Non-Interactive Install

Skip all prompts and use sensible defaults:

sudo AUTO_INSTALL=y ./amneziawg-install.sh

Override specific defaults with environment variables:

VariableDefault
SERVER_PUB_IPAuto-detected
SERVER_PUB_NICAuto-detected
SERVER_AWG_NICawg0
SERVER_AWG_IPV410.66.66.1
SERVER_AWG_IPV6fd42:42:42::1
ENABLE_IPV6y if the host has IPv6, otherwise n
SERVER_PORTRandom (49152–65535)
CLIENT_DNS_11.1.1.1
CLIENT_DNS_21.0.0.1
ALLOWED_IPS0.0.0.0/0, ::/0 (IPv4 only when ENABLE_IPV6=n)
CREATE_INITIAL_CLIENTyes in AUTO_INSTALL; prompted interactively

Set ENABLE_IPV6=n for an IPv4-only deployment: the server interface, firewall rules, and all generated client configs omit IPv6 (no IPv6 address, no ::/0 route), which avoids route-setup errors on hosts where IPv6 is disabled.

Example:

sudo AUTO_INSTALL=y SERVER_PORT=51820 CLIENT_DNS_1=8.8.8.8 ./amneziawg-install.sh

# IPv4-only server
sudo AUTO_INSTALL=y ENABLE_IPV6=n ./amneziawg-install.sh

🤖 Non-Interactive Client Management

The install script also supports non-interactive flags for automation and scripting:

# Add a new client
sudo ./amneziawg-install.sh --add-client alice

# Remove a client
sudo ./amneziawg-install.sh --remove-client alice

# List all clients
sudo ./amneziawg-install.sh --list-clients

🔐 Optional AWG 3.0 / 3.1 Mode

Warning

Incompatible with amneziawg-proxy: Do not enable AWG 3.0 or AWG 3.1 if you are using amneziawg-proxy. Because AmneziaWG 3.0+ incorporates the S1–S4 padding values as key material for header protection, the proxy's padding transformations corrupt header decryption and break packet classification.

If you require amneziawg-proxy, keep your interface in AWG 2.0 mode (the default). If an interface was already migrated to AWG 3.0 or 3.1, revert it to AWG 2.0 using sudo ./amneziawg-install.sh --disable-awg3 (or via the web panel under AWG protocol) before setting up or running the proxy.

Fresh installs and parameter files created by earlier releases use AWG 2.0 by default. Installing or upgrading this project never changes an existing interface's protocol mode. Existing AWG 3.0 installations stay on 3.0 until you explicitly enable AWG 3.1.

# Missing protocol state is reported as 2
sudo ./amneziawg-install.sh --protocol-status

# Probe userspace + running kernel support, then migrate the server and clients
sudo ./amneziawg-install.sh --enable-awg3

# Enable AWG 3.1 (AWG 3.0 plus RandomTrailers; DisableCookies stays off)
sudo ./amneziawg-install.sh --enable-awg31

# Atomically remove AWG 3.x-only fields and return every config to AWG 2.0
sudo ./amneziawg-install.sh --disable-awg3

AWG 3.0 header protection is interface-wide and cannot communicate with AWG 2.0 clients on the same interface. AWG 3.1 is AWG 3.0 plus RandomTrailers (must match on every peer) and optional DisableCookies (server-sent Cookie Reply / anti-DoS; default off). Enabling a mode creates or keeps one shared header key, validates all generated configs, and updates the server plus every recoverable client config as one transaction. If capability validation, file replacement, service restart, or the process itself fails, the previous state is restored. Redistribute every client config after a migration. The web panel exposes the same confirmed operations under AWG protocol.

When RandomTrailers is on, upstream recommends identical S1–S4 values to reduce packet-type misdetection. The installer warns if they differ and does not rewrite existing S-values.

What this installer implements

ModeFields
AWG 2.0Jc, Jmin, Jmax, S1–S4, H1–H4
AWG 3.0AWG 2.0 plus HeaderProtectionKey, optional ContentPaddingAddition, RekeyAfterTime, RekeyTimeout, RejectAfterTime, KeepaliveTimeout
AWG 3.1AWG 3.0 plus RandomTrailers and DisableCookies

Clients and the server must run AWG 3.1-capable implementations (amneziawg-tools plus the running kernel module, or an equivalent 3.1 userspace stack). The installer does not trust package version strings; it probes by applying the fields to a temporary interface and reading them back. I1–I5 (CPS) are intentionally not generated, persisted, or migrated. Upstream also defines optional MaxHandshakeAttempts; this installer does not manage that field (same as the existing AWG 3.0 mode). Externally added I1–I5 or MaxHandshakeAttempts lines are left in place during protocol rewrites.

📦 Requirements

Supported Linux distributions:

  • Debian ≥ 11
  • Ubuntu ≥ 22.04 (CI-tested on 22.04, 24.04, and 26.04)

Ubuntu 26.04 PPA compatibility

When the Amnezia PPA does not publish a resolute suite, the Ubuntu 26.04 (Resolute) installer uses the PPA's signed Ubuntu 24.04 (noble) suite as a temporary, narrowly scoped fallback:

  • The native resolute suite is checked first on every install or management run. Once it is published, the installer automatically stops using the fallback.
  • Network failures and unexpected HTTP responses do not trigger the fallback. Both native PPA metadata endpoints must explicitly report that the suite is absent.
  • Normal APT signature verification remains enabled. The installer does not add trusted=yes or allow insecure repositories.
  • The fallback is allowed on amd64, arm64, armhf, ppc64el, riscv64, and s390x, where the required package indexes are published. It is rejected on i386, which lacks amneziawg-tools.
  • Runtime module loading is continuously tested on the GitHub-hosted Ubuntu 26.04 amd64 image. Other listed architectures have package-index coverage but are not runtime-tested by this repository's CI.

Uninstalling AmneziaWG removes only source entries that exactly match the Amnezia PPA, including a fallback entry left by an interrupted older install. Unrelated APT sources in the same file are preserved.

Temporarily disabled:

  • Fedora (RPM-based)
  • AlmaLinux (RPM-based)
  • Rocky Linux (RPM-based)

Reason: verified AmneziaWG 2.0 packages are not currently available for these RPM-based distributions. Please watch this repository's releases and README for support status updates.

Source builds require approximately 2 GiB of free space for amneziawg-web and 1 GiB for amneziawg-proxy. Their install and upgrade scripts inspect the Cargo target filesystem, free inodes, CPU count, and available memory before building. On constrained hosts they use one Cargo job and, when the source filesystem is too small, place build artifacts on a suitable disk-backed filesystem automatically.

To select a specific build filesystem, create a writable directory on an executable mount and pass it explicitly:

sudo env AMNEZIAWG_BUILD_ROOT=/path/with/free-space ./amneziawg-web.sh upgrade
sudo env AMNEZIAWG_BUILD_ROOT=/path/with/free-space ./amneziawg-proxy.sh upgrade

An explicit CARGO_TARGET_DIR is also supported, but is treated as strict: the operation fails with a diagnostic if that target does not meet the build requirements.

⚙️ AmneziaWG 2.0 Parameters

Obfuscation Parameters

AmneziaWG 2.0 adds S3/S4 and H1–H4 range parameters for enhanced traffic obfuscation. The installer generates all values automatically.

ParameterRangeConstraint
Jc1–128—
Jmin1–1280Jmin ≤ Jmax
Jmax1–1280Jmin ≤ Jmax
S115–150S1 + 56 ≠ S2 and S2 + 56 ≠ S1
S215–150S1 + 56 ≠ S2 and S2 + 56 ≠ S1
S315–150S3 + 56 ≠ S4 and S4 + 56 ≠ S3
S415–150S3 + 56 ≠ S4 and S4 + 56 ≠ S3
H1–H45–2147483647Ranges must not overlap

H parameters accept a range (min-max) or a single value.

🔁 Migration from Pre-2.0

Run the installer on an existing pre-2.0 installation. It detects the need for migration and prompts before proceeding.

Important: All existing client configs become incompatible after migration. Regenerate them using option 1 (Add a new user) in the management menu.

Migration steps:

  1. Creates .bak backup files before making any changes.
  2. Generates new S3/S4 values with bidirectional constraint validation.
  3. Converts single H values to range format (or regenerates if overlapping).
  4. Updates server config and params file atomically.
  5. Renames outdated client configs with .old suffix.
  6. Reloads the running VPN service (if active).

Backups are restored automatically if migration fails.

🔒 Security Notes
  • Shell injection prevention — params file values are safely shell-quoted.
  • Atomic writes — config updates use a temp file + rename to prevent corruption on interruption.
  • Filesystem boundary protection — client config search uses -xdev to stay within the config filesystem.

Credits

Fork of RomikB/amneziawg-install.

Disclaimer

This is an independent, community-maintained project. It is not affiliated with, endorsed by, sponsored by, or otherwise associated with Amnezia (amnezia.org), the Amnezia VPN application, or the Amnezia Free VPN service. The project merely builds on the open-source AmneziaWG protocol and tooling. "Amnezia", "AmneziaWG", and any related names, logos, and trademarks are the property of their respective owners and are used here only for identification.

Likewise, this installer is provided as-is with no warranty (see License); you are responsible for how you deploy and use it.

License

MIT License