amneziawg-go

Linux

Run amnezia-wg instead of the default Linux kernel module.

macOS

Uses the utun driver. Due to Darwin limitations, it does not support sticky sockets or fwmarks.

• You must use an explicit interface name like utun[0-9]+ or use utun to let the kernel select one.
• If using utun, define the WG_TUN_NAME_FILE environment variable to record the actual interface name chosen by the kernel.
• Recommended usage: amneziawg-apple.

Windows

• Recommended usage: amneziawg-windows, which uses this implementation as a module.

To start an AmneziaWG interface, run the binary followed by the desired interface name. By default, the process will fork into the background.

To run in the foreground (useful for debugging), use the -f or --foreground flag.

To increase logging verbosity, set the LOG_LEVEL environment variable to debug.

Once running, you can manage the interface using standard networking tools like ip(8), ifconfig(8), or the amneziawg-tools package.

Building requires the latest version of Go.

$ git clone https://github.com/amnezia-vpn/amneziawg-go
$ cd amneziawg-go
$ make

To stop the interface and shut down the process, use one of the following methods:

1. Use standard networking commands: ip link del <interface_name>.
2. If the system does not support direct interface removal, remove the control socket: rm -f /var/run/amneziawg/<interface_name>.sock. This will trigger the amneziawg-go process to shut down.

Customize default WireGuard timings for handshakes and keepalives.

Device Settings (client-side):

• RekeyAfterTime: Time (seconds) after which the client tries a handshake.
• RekeyTimeout: Timeout (seconds) after which the handshake is repeated.
• RejectAfterTime: Time (seconds) after which the client forces a handshake and declines incoming data.
• KeepaliveTimeout: Time (seconds) since last data transmission before sending a keepalive.
• MaxHandshakeAttempts: Maximum number of handshake repetition attempts.

Peer Settings (client-side):

• PersistentKeepalive: Interval (seconds) of persistent keepalive.

You can customize the padding and header ranges for different message types in the handshake and transport phases.

Message Padding (S1-S4):

• S1: Handshake initial message
• S2: Handshake response message
• S3: Handshake cookie message
• S4: Transport messages

Message Headers (H1-H4):

• H1: Handshake initial message
• H2: Handshake response message
• H3: Handshake cookie message
• H4: Transport message

Header Value Formats:

• Range: x-y (e.g., 123-456)
• Single value: 1234

Custom signature packets are sent prior to every handshake in the order I1, I2, I3, I4, I5. If no value is specified, the packet is skipped.

• Scope: Recommended for client-side only.
• Warning: Ensure the final packet size does not exceed the system MTU to avoid fragmentation.

Supported Tags:

• <b 0x[seq]>: Static bytes (hex-encoded sequence).
• <r [size]>: Random bytes.
• <rd [size]>: Random digits ([0-9]).
• <rc [size]>: Random characters ([a-zA-Z]).
• <t>: 4-byte UNIX timestamp.

Junk packets are sent prior to every handshake to obfuscate the start of communication. They carry no actual data.

• Parameters:
  • Jc: Number of junk packets (recommended range: 4-12).
  • Jmin: Minimum random size.
  • Jmax: Maximum random size (Jmin <= Jmax).
• Scope: Recommended for client-side only.
• Warning: If Jmax exceeds the system MTU, the packet may be fragmented, which can be detected by censors.

Content padding allows for custom padding ranges to obfuscate traffic.

• Parameter: ContentPaddingAddition (uint32, range)
• Scope: client-side (not required to be the same on both sides, but recommended to specify on both).
• Format: a-b, a, or (off).

Header protection applies fast encryption to specific packet header fields used for authentication and encryption. It uses S1-S4 crypto padding as a nonce for each incoming packet.

• Parameter: HeaderProtectionKey (string)
• Scope: server-side (must be identical on both server and client)
• Requirement: S1-S4 values must be at least 12.
• Generation: Use awg genkey to generate the key.

The amneziawg-go process can be configured using several environment variables to control its behavior, especially when being managed by an external orchestrator or when using pre-allocated file descriptors.

When the amneziawg-go CLI tool exits, it uses the following exit codes:

• 0 (ExitSetupSuccess): Setup completed successfully.
• 1 (ExitSetupFailed): Setup failed (e.g., failed to create TUN device or UAPI listen error).