DOCSEARCHbyAlgolia
Submit Docs

AWG Manager

repository·master·Indexed 19 days ago

https://github.com/hoaxisr/awg-manager

A web-based management interface for Keenetic routers to control AmneziaWG and Sing-box VPN tunnels. It enables peer management, traffic monitoring, and DNS routing without a command-line interface. The project includes support for AWG 3.0 device parameters, kernel module management for various architectures (MIPS32 LE/BE, ARM aarch64), and tools for building amneziawg-go binaries and amneziawg-tools via the Keenetic SDK.

Tokens
43.2K
Snippets
138
Records
220
Agent score
66%

What's inside awg-manager

  1. Overview of AWG Manager features

    master

    AWG Manager is a web interface for managing AmneziaWG and Sing-box (vless tcp, hysteria, trojan, etc.) VPN tunnels directly on Keenetic routers via Entware (OPKG).

    Key capabilities include:

    • Browser-based management of AmneziaWG/Sing-box tunnels.
    • Peer management (add, remove, monitor).
    • Real-time speed tests and traffic graphing (1h / 3h / 24h periods).
    • Creation of AWG servers on the router.
    • DNS routing through tunnels via system WireGuard interfaces (NDMS) and Sing-box rule systems.
    • Real-time connection status monitoring.

  2. Overview of AmneziaWG kernel modules

    master

    The amneziawg kernel modules provide a kernel-mode backend for AmneziaWG. They are loaded using standard Linux networking commands:

    1. Create the interface: ip link add dev X type amneziawg
    2. Apply configuration: awg setconf

    Modules are provided as .ko files, typically one per Keenetic model group. The system uses internal/sys/kmod/loader.go to select the correct file based on the hardware.

    Supported Architectures:

    • MIPS32 LE (mt7621 / mt7628)
    • MIPS32 BE (en75xx)
    • ARM aarch64 (mt7622 / mt7981 / mt7988)

    Kernel Compatibility: All current modules target Linux 4.9-ndm. You can verify the kernel version compatibility of a module using:

    strings amneziawg-KN-XXXX.ko | grep vermagic

  3. Use the Stateful Mock Proxy for advanced simulation

    master

    The frontend/scripts/mock-proxy.mjs script acts as a middleware between Vite and Prism. It provides state-aware overrides that Prism (which is stateless) cannot do, such as:

    • Maintaining a persistent usageLevel between /settings/get and /settings/update.
    • Simulating singbox installation errors.
    • Providing fake singbox logs in the /logs endpoint.

    To use the full stateful simulation, you must run three processes simultaneously: Prism, the Mock Proxy, and the Frontend Dev Server.

    # Terminal A: Start Prism
cd frontend
npm run mock

# Terminal B: Start the Stateful Proxy
node frontend/scripts/mock-proxy.mjs

# Terminal C: Start Frontend pointing to the Proxy (e.g., on port 8081)
cd frontend
VITE_API_TARGET=http://127.0.0.1:8081 npm run dev:mock

  4. Requirements for AWG 3.0 (awg3) functionality

    master

    To use AWG 3.0 device parameters (such as HeaderProtectionKey, ContentPaddingAddition, and various timing ranges like RekeyAfterTime or KeepaliveTimeout), you must satisfy two requirements:

    1. awg3-capable modules: The kernel module must support the AWG 3.0 specification.
    2. awg3-capable awg tool: The user-space awg binary must be compatible with AWG 3.0 (refer to ../bin/README.md for details).

    Header Protection Constraint: When using header protection, the junk padding values S1–S4 must be ≥ 12.

    • S1: Handshake initiation
    • S2: Response
    • S3: Cookie
    • S4: Transport

    If padding is shorter than 12, the ChaCha20 nonces will mismatch between peers, causing all packets to be dropped. The awg setconf command will return -EINVAL if a key is provided alongside any $S_x$ value less than 12.

  5. Requirements for AWG 3.0 (awg3) CLI tool

    master

    To support AWG 3.0 device parameters, you must use a specific version of the awg CLI tool from the amnezia-vpn/amneziawg-tools repository (specifically tag v3.0.20260730).

    Standard/stock tools will reject the following AWG 3.0 configuration keys:

    • HeaderProtectionKey
    • ContentPaddingAddition
    • RekeyAfterTime
    • RekeyTimeout
    • RejectAfterTime
    • KeepaliveTimeout
    • MaxHandshakeAttempts

    The required tool parses these keys and serializes them to netlink. It is safe to replace the tool before the kernel modules are updated, as it negotiates the netlink family version (version 2 for AWG 2.0, version 3 for awg3) and falls back to the older format if necessary.

  6. Build amneziawg-tools using the Keenetic SDK

    master

    To build the amneziawg-tools package for Keenetic devices, use the Keenetic SDK. Note that you must avoid the sed command used in the package Makefile that renames the generic netlink family to "wireguard", as this causes the tool to communicate with the standard kernel WireGuard module instead of amneziawg.

    Build Steps:

    1. Navigate to keenetic-sdk/package/net/amneziawg-tools.
    2. Run ./configure.sh <MODEL>.
    3. Run make package/net/amneziawg-tools/compile.

    Model Mapping:

    • KN-1810: mipsel
    • KN-2010: mips
    • KN-1812: aarch64
    ./configure.sh <MODEL>
make package/net/amneziawg-tools/compile

  7. Apply patches to wdtt-server for Keenetic / awg-manager

    master

    To use wdtt with Keenetic routers or awg-manager, you must apply a specific sequence of patches to the wdtt source code (specifically targeting the v1.4.62 tag at server/cmd).

    Required Patch Order:

    1. no-nat.patch
    2. panel-db.patch
    3. wg-iface.patch

    Patch Descriptions

    no-nat.patch

    • Adds the -no-nat flag: prevents the server from touching iptables/nft and ip_forward (since awg-manager handles NAT on the router).
    • Adds the -nat-if eth3 flag: allows specifying an explicit WAN interface for built-in MASQUERADE if -no-nat is not used.
    • Includes cleanup logic: removes WDTT_MANAGED rules and nft wdtt tables upon shutdown.

    panel-db.patch

    • Moves panel.db to {config-dir}/panel.db instead of the hardcoded /etc/wdtt/panel.db.
    • Enables auto-creation: automatically initializes SQLite and wdtt_* tables on the first run (useful for headless operation without a web panel).
    • Note: This is required for GETCONF functionality; without panel.db, the server responds with NOCONF.

    wg-iface.patch

    • Adds the -wg-iface <name> flag: allows specifying the userspace WireGuard interface name (defaults to wdtt0).
    • This is necessary for registering WDTT in NDMS as OpkgTun17..49, enabling NAT/LAN/policy management via router ip nat and ACLs, similar to managed WireGuard.

  8. Build AmneziaWG-Go binaries from source

    master

    If pre-built binaries are unavailable, you can build the userspace WireGuard daemon (amneziawg-go) for specific architectures using Go. Ensure you set the correct GOOS, GOARCH, and GOMIPS environment variables.

    # For mipsle
GOOS=linux GOARCH=mipsle GOMIPS=softfloat go build -o amneziawg-go-mipsle ./main.go

# For arm64
GOOS=linux GOARCH=arm64 go build -o amneziawg-go-arm64 ./main.go

  9. Use genpresets to update the preset catalog

    master

    The genpresets tool is a developer utility used to maintain internal/presets/defaults.json. It works by loading the existing catalog as a base, re-decompiling .srs files using a host sing-box to refresh inlined DNS domains/subnets, and appending new presets defined in the additions table within catalog.go.

    Workflow:

    1. Download a pinned sing-box: You must use a sing-box binary that matches the project's RequiredVersion (defined in internal/singbox/installer/embedded.go) to ensure compatibility with the .srs rule-set format.
    2. Generate: Run the tool pointing to the downloaded binary.
    3. Review: Check the changes made to internal/presets/defaults.json via git diff and commit the updated file.

    Important Constraints:

    • Environment: Do not run this on a router or in CI. It requires network access to download .srs files and a host sing-box binary.
    • DNS Limits: DNS domains with more than 500 entries (e.g., category-ads-all) are not inlined; these presets remain sing-box-only.
    • Rule Types: domain_keyword and domain_regex rules are skipped and logged because they cannot be expressed by the DNS engine.
    • Determinism: The output is sorted by category and then ID to ensure stable diffs.
    # 1) get a host sing-box pinned to the project's runtime version
ver="$(sed -n 's/^const RequiredVersion = "\(.*\)"/\1/p' internal/singbox/installer/embedded.go)"
curl -fsSL -o /tmp/sb.tgz "https://github.com/SagerNet/sing-box/releases/download/v${ver}/sing-box-${ver}-linux-amd64.tar.gz"
tar -xzf /tmp/sb.tgz -C /tmp
SB=$(find /tmp -type f -name sing-box -path "*${ver}-linux-amd64*" | head -1)

# 2) generate — base is read from internal/presets/defaults.json, then rewritten
go run ./tools/genpresets -singbox "$SB"

# 3) review the diff and commit internal/presets/defaults.json
git diff internal/presets/defaults.json

  10. Annotate Go handlers for OpenAPI/Swagger

    master

    The project uses swag to generate OpenAPI (Swagger) YAML files from Go annotations. To document an API endpoint, add swagger-style comments directly above the named function or method in internal/api/*.

    Common annotations include:

    • @Summary: A short description of the endpoint.
    • @Tags: Grouping for the endpoint.
    • @Accept / @Produce: Content types (e.g., json).
    • @Param: Defines query, path, or body parameters.
    • @Success / @Failure: Defines response types and status codes.
    • @Security: Specifies security requirements (e.g., CookieAuth).
    • @Router: Defines the path and HTTP method (e.g., /path [get]).

    Global API metadata and the CookieAuth security schema are defined in cmd/awg-manager/docs.go.

    // GetSystemInfo godoc
// @Summary      Системная информация
// @Tags         system
// @Produce      json
// @Security     CookieAuth
// @Success      200 {object} map[string]interface{}
// @Failure      500 {object} response.ErrorResponse
// @Router       /system/info [get]
func (h *SystemHandler) Info(w http.ResponseWriter, r *http.Request) {
	// handler logic
}

  11. Build wdtt-server for Entware arm64

    master

    Use the following steps to build the patched wdtt-server for arm64 architectures.

    Important Architecture Limitation: This build process is only compatible with arm64. The upstream pkg/paneldb depends on modernc.org/sqlite → modernc.org/libc, which does not support mips or mipsle. It is impossible to build wdtt-server for mipsel-3.4 or mips-3.4 using this method.

    Build Command:

    git clone --branch v1.4.62 https://github.com/ildarmaga/wdtt.git
cd wdtt
git apply /path/to/no-nat.patch
git apply /path/to/panel-db.patch
git apply /path/to/wg-iface.patch
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -trimpath -ldflags="-s -w" \
  -o wdtt-server-linux-arm64 ./server/cmd

  12. Access the Swagger UI

    master
    Once the backend (daemon) and the frontend development server are running, you can view the interactive API documentation at the /api-docs endpoint. The UI fetches the specification from the runtime endpoint GET /api/openapi.yaml.