wgctrl

README

awgctrl-go

A Go library for controlling WireGuard and AmneziaWG devices on Linux.

Fork of WireGuard/wgctrl-go extended with complete AmneziaWG v2 support — reading and writing all AWG obfuscation parameters via netlink, parameter validation, auto-generation, and userspace daemon support.

What's new compared to wgctrl-go

Feature	wgctrl-go	awgctrl-go
Standard WireGuard	✅	✅
AmneziaWG — write params	❌	✅
AmneziaWG — read params	❌	✅
Peer-level AdvancedSecurity	❌	✅
Auto-generate AWG params	❌	✅
Validate AWG params	❌	✅
Userspace AWG daemon	❌	✅
context.Context API	❌	✅
Single netlink round-trip	❌	✅

Platform support

Platform	Kernel WG	Kernel AWG	Userspace WG	Userspace AWG
Linux	✅	✅	✅	✅
FreeBSD	✅	❌	✅	❌
OpenBSD	✅	❌	✅	❌
Windows	❌	❌	✅	❌

Requirements

• Go 1.21 or later
• Linux kernel with AmneziaWG module (modprobe amneziawg), or amneziawg-go userspace daemon
• Root privileges or CAP_NET_ADMIN capability

This library works with any AmneziaWG v2 kernel module, including the upstream module. For production use we recommend the patched fork which fixes netlink dump overflow with many peers, a cookie reply size bug, sysfs race conditions, and adds DKMS/kernel 6.19+ compatibility.

AWG kernel and userspace support is Linux-only. Other platforms (FreeBSD, OpenBSD, Windows) support standard WireGuard only.

Installation

go get github.com/awg-go/awgctrl-go

Quick start

Read a device

client, err := wgctrl.New()
if err != nil {
    log.Fatal(err)
}
defer client.Close()

device, err := client.Device(context.Background(), "awg0")
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Interface: %s  IsAmnezia: %v\n", device.Name, device.IsAmnezia)
for _, peer := range device.Peers {
    fmt.Printf("Peer: %s  AWG: %v  RX: %d  TX: %d\n",
        peer.PublicKey, peer.AdvancedSecurity,
        peer.ReceiveBytes, peer.TransmitBytes)
}

Enable AWG obfuscation

The simplest approach — all parameters are generated automatically:

cfg := &wgtypes.Config{}
cfg.GenerateAmneziaParams()

if err := cfg.Validate(); err != nil {
    log.Fatal(err)
}

client.ConfigureDevice(context.Background(), "awg0", *cfg)

Add a peer with AWG

pubKey, _ := wgtypes.ParseKey("base64encodedpublickey=")
_, allowedIP, _ := net.ParseCIDR("10.0.0.2/32")

cfg := wgtypes.Config{
    Peers: []wgtypes.PeerConfig{
        {
            PublicKey:        pubKey,
            AllowedIPs:       []net.IPNet{*allowedIP},
            AdvancedSecurity: true,
        },
    },
}

client.ConfigureDevice(context.Background(), "awg0", cfg)

Documentation

• AWG Parameter Reference — Jc, Jmin, Jmax, S1–S4, H1–H4, I1–I5 with limits, rules and examples
• Peer Advanced Security — how the kernel determines per-peer AWG status
• Examples — practical usage examples
• pkg.go.dev — full API reference

License

MIT — Copyright (C) 2018-2022 Matt Layher, 2025 Advanced-WG, V. Bantserov. See LICENSE.md.

Documentation

Overview

Copyright (C) 2018-2022 Matt Layher Copyright (C) 2025 Advanced-WG, V. Bantserov

Package wgctrl enables control of WireGuard and AmneziaWG devices on multiple platforms.

For more information on WireGuard, please see https://www.wireguard.com/. For AmneziaWG, see https://github.com/amnezia-vpn/amneziawg-linux-kernel-module.

This package is a fork of WireGuard/wgctrl-go with full AmneziaWG support:

• Reading AWG parameters (Jc, Jmin, Jmax, S1-S4, H1-H4, I1-I5) via Device()
• Writing AWG parameters via ConfigureDevice()
• Automatic parameter generation via Config.GenerateAmneziaParams()
• Parameter validation via Config.Validate()
• Userspace AWG daemon support (amneziawg-go)

Index

• type Client
  • func New() (*Client, error)
  • func (c *Client) Close() error
  • func (c *Client) ConfigureDevice(ctx context.Context, name string, cfg wgtypes.Config) error
  • func (c *Client) Device(ctx context.Context, name string) (*wgtypes.Device, error)
  • func (c *Client) Devices(ctx context.Context) ([]*wgtypes.Device, error)

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

A Client provides access to WireGuard device information.

func New

func New() (*Client, error)

New creates a new Client.

func (*Client) Close

func (c *Client) Close() error

Close releases resources used by a Client.

All underlying clients are closed regardless of errors. If multiple clients fail to close, their errors are joined with errors.Join so callers can inspect individual errors via errors.Is / errors.As.

func (*Client) ConfigureDevice

func (c *Client) ConfigureDevice(ctx context.Context, name string, cfg wgtypes.Config) error

ConfigureDevice configures a WireGuard device by its interface name.

Because the zero value of some Go types may be significant to WireGuard for Config fields, only fields which are not nil will be applied when configuring a device.

If the device specified by name does not exist or is not a WireGuard device, an error is returned which can be checked using `errors.Is(err, os.ErrNotExist)`.

func (*Client) Device

func (c *Client) Device(ctx context.Context, name string) (*wgtypes.Device, error)

Device retrieves a WireGuard device by its interface name.

If the device specified by name does not exist or is not a WireGuard device, an error is returned which can be checked using `errors.Is(err, os.ErrNotExist)`.

func (*Client) Devices

func (c *Client) Devices(ctx context.Context) ([]*wgtypes.Device, error)

Devices retrieves all WireGuard devices on this system.

When multiple backend clients report the same device (identified by interface name), only the first occurrence is kept. This prevents duplicates when, for example, both kernel and userspace clients discover the same interface.