AmneziaWG Windows Library

The interfaceWatcher struct is used to monitor Windows network interface changes and automatically reconfigure the tunnel's IP addresses when relevant changes occur.

Lifecycle and Usage

1. Initialization: Call watchInterface() to start monitoring. This registers a callback via winipcfg.RegisterInterfaceChangeCallback that listens for winipcfg.MibAddInstance notifications.
2. Configuration: Once the watcher is initialized, call Configure(binder, conf, tun) to provide the necessary dependencies. This method also processes any interface change events that occurred while the watcher was running but before the tunnel was ready.
3. Cleanup: Call Destroy() to unregister all callbacks, disable the firewall, and flush routes, IP addresses, and DNS settings associated with the tunnel's LUID to ensure a clean teardown of the Windows networking stack.

Error Handling

Errors encountered during interface setup are sent to the errors channel of the interfaceWatcher instance as interfaceWatcherError objects, which wrap a services.Error and the underlying error.

iw, err := watchInterface()
if err != nil {
    log.Fatal(err)
}

// ... later, once tunnel and config are ready ...

iw.Configure(binder, config, tun)

// ... on shutdown ...

iw.Destroy()

To start the AmneziaWG tunnel as a Windows service, use the Run function. This function wraps the standard Windows service execution logic, handling interface creation (Wintun), privilege dropping, firewall configuration, and UAPI listening.

Parameters

• confString: A string containing the WireGuard configuration (compatible with wg-quick format).
• tunnelName: The name of the service to be registered in the Windows Service Control Manager (SCM).

Behavior

• Configuration: Parses the confString using conf.FromWgQuickWithUnknownEncoding and deduplicates network entries.
• Interface: Attempts to create a Wintun interface using a deterministic GUID based on the configuration.
• Lifecycle Hooks: Executes PreUp, PostUp, PreDown, and PostDown script commands defined in the configuration.
• Privileges: Automatically drops all privileges after setting up the network interface and firewall to enhance security.
• UAPI: Starts a listener for User API requests to allow external control of the tunnel.
• Error Handling: Maps internal errors to specific service error codes via services.DetermineErrorCode for better visibility in Windows Service logs.

import "github.com/amnezia-vpn/amneziawg-windows/v3"

func main() {
    confString := `[Interface]
PrivateKey = <key>
Address = 10.0.0.1/24`
    tunnelName := "amneziawg-tunnel"

    err := amneziawg.Run(confString, tunnelName)
    if err != nil {
        log.Fatalf("Service failed: %v", err)
    }
}

The CopyConfigOwnerToIPCSecurityDescriptor function synchronizes the permissions of the Inter-Process Communication (IPC) mechanism with the owner of a specific configuration file.

This ensures that the user who owns the configuration file also has full access (GENERIC_ALL) to the IPC interface. The function performs the following logic:

1. Checks if the filename is encrypted using conf.PathIsEncrypted. If so, it returns nil.
2. Retrieves the owner SID of the provided filename using Windows security APIs.
3. If the owner is the WinLocalSystemSid, it skips the update.
4. Creates a new Access Control Entry (ACE) granting GENERIC_ALL access to the file owner.
5. Updates the global ipc.UAPISecurityDescriptor with a new Discretionary Access Control List (DACL) that includes this additional entry.

This is used to prevent permission mismatches where a user might own a VPN configuration but be unable to communicate with the background service via IPC.

err := CopyConfigOwnerToIPCSecurityDescriptor("path/to/config.conf")
if err != nil {
    // handle error
}

When the Run function fails, it returns error codes mapped to specific failure points. These are used by the Windows Service Control Manager to diagnose issues. Common error mappings include: