Skip to content

amneziawg-tools: add AmneziaWG userspace tools package - #30493

Open
karen07 wants to merge 1 commit into
openwrt:masterfrom
karen07:add-amneziawg-tools
Open

amneziawg-tools: add AmneziaWG userspace tools package#30493
karen07 wants to merge 1 commit into
openwrt:masterfrom
karen07:add-amneziawg-tools

Conversation

@karen07

@karen07 karen07 commented Sep 9, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

AmneziaWG OpenWrt integration — 2/3

This PR adds the amneziawg-tools userspace package.

It is the second part of a complete AmneziaWG integration for OpenWrt:

  1. kmod-amneziawg — kernel module: kmod-amneziawg: add AmneziaWG kernel module package #30492
  2. amneziawg-tools — userspace tools (this PR)
  3. luci-proto-amneziawg — LuCI protocol integration (to be submitted)

Depends on: #30492

Maintenance and provenance

I maintain the complete OpenWrt integration here:

https://github.com/karen07/amneziawg-openwrt-package

The repository is built around a generator:

https://github.com/karen07/amneziawg-openwrt-package/blob/main/generate.py

The goal is to avoid maintaining a large, manually diverging copy of the
corresponding WireGuard OpenWrt integration.

For amneziawg-tools, the generator currently uses the OpenWrt 25.12
WireGuard package as its baseline.

This is intentional: OpenWrt 25.12 is the stable WireGuard integration that
still uses the shell-based netifd protocol handler, which is also the
implementation currently used and tested by this AmneziaWG port.

OpenWrt master has since migrated the WireGuard protocol handler to ucode.
The AmneziaWG protocol helper in this submission remains shell-based.
Shell protocol handlers are still supported by netifd.

A future migration of the AmneziaWG protocol helper to the current ucode
WireGuard baseline can be handled separately without changing the upstream
AmneziaWG userspace tooling itself.

Reproducible generation

generate.py is the source of truth for the generated packages.

The generation process is split into deterministic stages:

vanilla -> files -> text -> full

These stages separate:

  • the original OpenWrt 25.12 WireGuard package;
  • file and path renames;
  • mechanical WireGuard-to-AmneziaWG identifier renames;
  • the actual AmneziaWG-specific changes.

The important review boundary is text -> full.

At the text stage, the package has already been mechanically transformed
from WireGuard to AmneziaWG. The full stage then adds only the
AmneziaWG-specific integration.

This makes the actual AmneziaWG delta directly reviewable instead of requiring
reviewers to inspect a large copied WireGuard implementation as a whole.

Example comparison:

WireGuard-derived baseline -> AmneziaWG-specific changes

For this PR, the relevant files in that comparison are under
amneziawg-tools/.

The generator is maintenance and review tooling only. The generated files are
committed to Git, so OpenWrt does not depend on the generator at package build
time.

Upstream tracking

The AmneziaWG userspace source is pinned to an official upstream release tag:

https://github.com/amnezia-vpn/amneziawg-tools

The generator also provides:

./generate.py check

to check whether a newer AmneziaWG kernel-module or tools release is
available.

I run this check manually on a regular basis, normally daily.

When a new upstream version is detected, it is not applied silently. The
version change must be reviewed explicitly before regeneration.

Build and testing workflow

I use this AmneziaWG OpenWrt integration myself.

The maintenance repository also contains GitHub Actions / OpenWrt SDK build
workflows for building the generated packages across OpenWrt
target/subtarget combinations.

The same repository can also be used to build and install the packages
directly on an OpenWrt device for local testing.

This is intended to be a maintained integration rather than a one-off
packaging attempt.

Previous submission

A previous amneziawg-tools submission exists as #26972.

I reviewed the feedback from that submission while preparing this version.

The reproducible generation approach is intended to make the package
provenance explicit and keep the WireGuard-derived part separate from the
actual AmneziaWG-specific changes.

PR series

@karen07
karen07 force-pushed the add-amneziawg-tools branch from fdecefb to 64185ab Compare September 9, 2026 16:09
@karen07 karen07 mentioned this pull request Sep 9, 2026
Open
@BKPepe

BKPepe commented Sep 9, 2026

Copy link
Copy Markdown
Member

There is already opened PR #26972, what is different between this and that?

@karen07
karen07 force-pushed the add-amneziawg-tools branch from 64185ab to 4c2577d Compare September 9, 2026 23:09
@karen07

karen07 commented Sep 9, 2026

Copy link
Copy Markdown
Contributor Author

Thanks for pointing that out.

There are a few differences compared to #26972:

  • amneziawg-tools: add new package #26972 currently packages amneziawg-tools v1.0.20250903, while this PR tracks the current v3.1.20260812 release.
  • This version includes the AWG 3.1-specific configuration options, including HeaderProtectionKey, ContentPaddingAddition, RekeyAfterTime, RekeyTimeout, RejectAfterTime, KeepaliveTimeout, MaxHandshakeAttempts, RandomTrailers and DisableCookies.
  • The netifd integration here was re-derived from the OpenWrt 25.12 wireguard-tools implementation and kept as close to that baseline as possible, with only the AmneziaWG-specific changes on top. This includes the current shell helper behaviour such as peer detection/renew handling and in-memory configuration via syncconf.
  • I also reviewed the feedback on amneziawg-tools: add new package #26972 and avoided the issues pointed out there, such as the kernel/userspace detection error and the stale WireGuard watchdog references.

The intention of this PR is therefore not just to duplicate #26972, but to provide an updated AWG 3.1 integration while keeping the OpenWrt-specific code closely aligned with the existing WireGuard implementation.

@karen07
karen07 force-pushed the add-amneziawg-tools branch from 44a43d5 to 4c2577d Compare September 10, 2026 00:43
openwrt-ai
openwrt-ai reviewed Sep 10, 2026
View reviewed changes
Comment thread net/amneziawg-tools/files/amneziawg.sh Outdated
Comment on lines +139 to +140
config_get awg_random_trailers "${config}" "awg_random_trailers"
config_get awg_disable_cookies "${config}" "awg_disable_cookies"

@openwrt-ai openwrt-ai Sep 10, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

config_get hands back the raw UCI string, so the perfectly valid UCI boolean spellings true/false/yes/no/enabled/disabled reach awg unchanged, and parse_bool in config.c:421-446 accepts only on/off or a digit — anything else makes syncconf exit non-zero, which aborts the whole interface setup, not just that one option. Use config_get_bool with an empty default so set values normalize to 0/1 while unset ones stay omitted.

Suggested change
config_get awg_random_trailers "${config}" "awg_random_trailers"
config_get awg_disable_cookies "${config}" "awg_disable_cookies"
config_get_bool awg_random_trailers "${config}" "awg_random_trailers" ""
config_get_bool awg_disable_cookies "${config}" "awg_disable_cookies" ""

Generated by Claude Code

@openwrt-ai openwrt-ai Sep 10, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixed, thanks

Generated by Claude Code

Comment thread net/amneziawg-tools/Makefile Outdated
Comment on lines +17 to +20
PKG_SOURCE_PROTO:=git
PKG_SOURCE_URL:=https://github.com/amnezia-vpn/amneziawg-tools.git
PKG_SOURCE_VERSION:=v$(PKG_VERSION)
PKG_MIRROR_HASH:=0c27841a3b4860c7fd085cd627c5b0f9c25653afdaef1e73fd3e350fb3445dab

@openwrt-ai openwrt-ai Sep 10, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PKG_SOURCE_PROTO:=git is meant as a last resort for upstreams with no release archive, but v3.1.20260812 is a real tag and the tree carries no submodules, so a plain tarball works here. Please switch to PKG_SOURCE/PKG_SOURCE_URL + PKG_HASH the way the rest of the feed fetches GitHub releases, e.g. libs/libyang/Makefile:14-16.

Generated by Claude Code

@openwrt-ai openwrt-ai Sep 10, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixed, thanks

Generated by Claude Code

Comment thread net/amneziawg-tools/Makefile Outdated
Comment on lines +46 to +51
AmneziaWG is a novel VPN that runs inside the Linux Kernel and utilizes
state-of-the-art cryptography. It aims to be faster, simpler, leaner, and
more useful than IPSec, while avoiding the massive headache. It intends to
be considerably more performant than OpenVPN. AmneziaWG is designed as a
general purpose VPN for running on embedded interfaces and super computers
alike, fit for many different circumstances. It uses UDP.

@openwrt-ai openwrt-ai Sep 10, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: this paragraph is the WireGuard blurb with the name substituted, so it never mentions the configurable traffic obfuscation that the commit message and PR body give as the reason this package exists. Worth a sentence saying it is a WireGuard-derived protocol with DPI-evasion parameters, so menuconfig users can tell the two packages apart.

Generated by Claude Code

@openwrt-ai openwrt-ai Sep 10, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixed, thanks

Generated by Claude Code

@karen07
karen07 force-pushed the add-amneziawg-tools branch from 4c2577d to 88e2566 Compare September 10, 2026 07:24
openwrt-ai
openwrt-ai reviewed Sep 10, 2026
View reviewed changes

@openwrt-ai openwrt-ai left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed 1 new commit; no new issues found.

Generated by Claude Code

@karen07
karen07 force-pushed the add-amneziawg-tools branch from 88e2566 to 4e2cdbd Compare September 10, 2026 14:19
@karen07
karen07 requested a review from openwrt-ai September 10, 2026 15:00
openwrt-ai
openwrt-ai reviewed Sep 10, 2026
View reviewed changes

@openwrt-ai openwrt-ai left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed 1 new commit; no new issues found.

Generated by Claude Code

@karen07
karen07 requested a review from openwrt-ai September 10, 2026 17:12
@karen07
karen07 force-pushed the add-amneziawg-tools branch 2 times, most recently from 33d8311 to b0f2cb9 Compare September 12, 2026 17:20
openwrt-ai
openwrt-ai reviewed Sep 13, 2026
View reviewed changes

@openwrt-ai openwrt-ai left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed 1 new commit; no new issues found.

Generated by Claude Code

@karen07
karen07 requested a review from openwrt-ai September 14, 2026 14:49
@Ser9ei

Ser9ei commented Sep 15, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

I’d like to point out that wireguard-tools in master has already moved from shell scripts to ucode. It would be nice to do the same for amneziawg-tools, but I’d suggest treating this as a change request after the current changes are accepted.

ps
Perhaps it would have been simpler to have a single PR in openwrt/packages for both the kernel module and tools, split into two commits, but this approach is fine too, of course.

@BKPepe
BKPepe force-pushed the add-amneziawg-tools branch from b0f2cb9 to e23b5fb Compare September 21, 2026 09:32
openwrt-ai
openwrt-ai reviewed Sep 21, 2026
View reviewed changes

@openwrt-ai openwrt-ai left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed 1 new commit; no new issues found.

Generated by Claude Code

@karen07
amneziawg-tools: add AmneziaWG userspace tools package
6456a8c 
AmneziaWG is a WireGuard-based VPN protocol with configurable traffic
obfuscation features. This package provides the AmneziaWG userspace
tools for OpenWrt.

Signed-off-by: Karen Khachatryan <karen0734@gmail.com>
@karen07
karen07 force-pushed the add-amneziawg-tools branch from e23b5fb to 6456a8c Compare September 22, 2026 09:38
openwrt-ai
openwrt-ai reviewed Sep 22, 2026
View reviewed changes

@openwrt-ai openwrt-ai left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed 1 new commit; no new issues found.

Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

1 more reviewer
@openwrt-ai openwrt-ai openwrt-ai left review comments
Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

Add package

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@karen07 @BKPepe @Ser9ei @openwrt-ai