WireGuard Tools

https://github.com/wireguard/wireguard-tools
Admin
This project supplies the main userspace tooling for using and configuring WireGuard tunnels,...
Tokens:40,625
Snippets:235
Trust Score:9.2
License:GPL-2.0
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Example usage of key encoding helpers

Source: https://github.com/wireguard/wireguard-tools/blob/master/_autodocs/api-reference/encoding.md

Complete example showing how to decode a base64 key, encode it to hex and base64, and check for all-zero keys. Uses the provided key string and prints errors on failure.

```c
#include "encoding.h"

uint8_t key[WG_KEY_LEN] = { 0 };
char b64[WG_KEY_LEN_BASE64];
char hex[WG_KEY_LEN_HEX];

if (!key_from_base64(key, "yAnz5TF+lXXJte14tji3zlMNq+hd2rYUIgJBgB3fBmk=")) {
	fprintf(stderr, "bad key\n");
	return 1;
}
key_to_hex(hex, key);       /* 64 lowercase hex chars */
key_to_base64(b64, key);    /* round-trips to the input form */
if (key_is_zero(key)) {
	fprintf(stderr, "key is all zeros\n");
	return 1;
}
```

--------------------------------

### Example: derive and print public key

Source: https://github.com/wireguard/wireguard-tools/blob/master/_autodocs/api-reference/curve25519.md

Example usage: fills a private key, clamps it, derives the public key, and prints it in base64. Requires WG_KEY_LEN and WG_KEY_LEN_BASE64 from types.h and key_to_base64 from encoding.h.

```c
#include "curve25519.h"
#include "encoding.h"

uint8_t priv[WG_KEY_LEN], pub[WG_KEY_LEN];
/* priv filled by getentropy()/getrandom()/urandom ... */
curve25519_clamp_secret(priv);
curve25519_generate_public(pub, priv);

char b64[WG_KEY_LEN_BASE64];
key_to_base64(b64, pub);
printf("public: %s\n", b64);
```

--------------------------------

### wg(8) configuration file example

Source: https://github.com/wireguard/wireguard-tools/blob/master/_autodocs/configuration.md

Example configuration file for wg(8), showing an [Interface] section with PrivateKey and ListenPort, and a [Peer] section with PublicKey, Endpoint, and AllowedIPs. This format is consumed by wg setconf, wg addconf, and wg syncconf, and emitted by wg showconf.

```ini
[Interface]
PrivateKey = yAnz5TF+lXXJte14tji3zlMNq+hd2rYUIgJBgB3fBmk=
ListenPort = 51820

[Peer]
PublicKey = xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg=
Endpoint = 192.95.5.67:1234
AllowedIPs = 10.192.122.3/32, 10.192.124.1/24

```

--------------------------------

### Install wireguard-tools

Source: https://github.com/wireguard/wireguard-tools/blob/master/README.md

Install the built tools system-wide using make install. The installation respects environment variables like PREFIX, DESTDIR, and others to customize the installation paths and features.

```shell
    # make install
```

--------------------------------

### IPC layer example: list, get, and set WireGuard devices

Source: https://github.com/wireguard/wireguard-tools/blob/master/_autodocs/api-reference/ipc-layer.md

Example usage of the IPC layer functions: ipc_list_devices, ipc_get_device, and ipc_set_device. It lists all WireGuard devices, retrieves the device named "wg0", sets its fwmark to 0xca6c with the WGDEVICE_HAS_FWMARK flag, and applies the change. On failure, it prints an error via perror and returns 1; note that errno is set by the IPC functions (e.g., ENODEV via netlink).

```c
#include "ipc.h"
#include "containers.h"

int main(void)
{
	struct wgdevice *dev = NULL;
	char *names;

	names = ipc_list_devices();
	if (!names) {
		perror("list devices");           /* errno set */
		return 1;
	}
	for (char *p = names; *p; p += strlen(p) + 1)
		printf("%s\n", p);
	free(names);

	if (ipc_get_device(&dev, "wg0") != 0) {
		perror("get wg0");                /* e.g. ENODEV via netlink */
		return 1;
	}
	dev->fwmark = 0xca6c;
	dev->flags |= WGDEVICE_HAS_FWMARK;
	if (ipc_set_device(dev) != 0) {
		perror("set fwmark");
		free_wgdevice(dev);
		return 1;
	}
	free_wgdevice(dev);
	return 0;
}
```

--------------------------------

### Round-trip showconf and setconf

Source: https://github.com/wireguard/wireguard-tools/blob/master/_autodocs/api-reference/wg.md

Round-trip example: dump the current configuration of interface wg0 to wg0.conf, edit the ListenPort value with sed, and reapply the configuration with wg setconf. Demonstrates how to modify a running interface without disruption.

```bash
# Round-trip: dump current config, edit it, reapply without disruption
wg showconf wg0 > wg0.conf
sed -i 's/^ListenPort = .*/ListenPort = 51821/' wg0.conf
wg setconf wg0 wg0.conf
```

--------------------------------

### wg setconf, addconf, syncconf: usage examples

Source: https://github.com/wireguard/wireguard-tools/blob/master/_autodocs/api-reference/wg-set.md

Shows the three subcommands: setconf for full replacement, addconf for appending peers, and syncconf for non-disruptive reload. Also includes error handling for a malformed configuration file, which aborts with exit 1.

```bash
# Full replace (setconf)
wg setconf wg0 /etc/wireguard/wg0.conf

# Append peers from an extra file
wg addconf wg0 extra-peers.conf

# Non-disruptive reload of a running interface
wg syncconf wg0 <(wg-quick strip wg0)

# Error handling: malformed file aborts with exit 1 and a diagnostic
if ! wg setconf wg0 broken.conf; then
    echo "config rejected" >&2
fi
```

--------------------------------

### Error handling for wg-quick up

Source: https://github.com/wireguard/wireguard-tools/blob/master/_autodocs/api-reference/wg-quick.md

Error handling example: run wg-quick up and capture stderr to a file, then check the exit status. On failure, display the error message, e.g. "wg-quick: `wg0' does not exist".

```bash
# Error handling
if wg-quick up wg0 2>wg-quick.err; then
    echo "interface wg0 is up"
else
    cat wg-quick.err   # e.g. "wg-quick: `wg0' does not exist"
fi
```

--------------------------------

### wg show examples

Source: https://github.com/wireguard/wireguard-tools/blob/master/_autodocs/api-reference/wg.md

Common invocations of the wg show subcommand: pretty-print, list interfaces, script-friendly field output, and full dump. The dump output is consumed by contrib/json/wg-json.

```bash
# Pretty-print everything on the default interface set
wg

# Names of all WireGuard interfaces
wg show interfaces

# Script-friendly per-interface data
wg show wg0 transfer
wg show all endpoints

# Full dump (this is the stream consumed by contrib/json/wg-json)
wg show all dump
```

--------------------------------

### terminal_printf usage example

Source: https://github.com/wireguard/wireguard-tools/blob/master/_autodocs/api-reference/terminal.md

Example usage of terminal_printf with cyan bold text. When colorization is disabled (WG_COLOR_MODE=never or non-TTY stdout), the output is plain "hello" without ANSI sequences.

```c
#include "terminal.h"

terminal_printf(TERMINAL_FG_CYAN TERMINAL_BOLD "%s" TERMINAL_RESET "\n", "hello");
/* With WG_COLOR_MODE=never (or non-TTY stdout), output is plain "hello". */

```

--------------------------------

### Build wireguard-tools from source

Source: https://github.com/wireguard/wireguard-tools/blob/master/README.md

Build the project by changing into the src directory and running make. There are no dependencies other than a good C compiler and a sane libc.

```shell
    $ cd src
    $ make
```

--------------------------------

### wg-quick up, strip, syncconf, save, and down commands

Source: https://github.com/wireguard/wireguard-tools/blob/master/_autodocs/api-reference/wg-quick.md

Common wg-quick commands: bring up an interface from a config file (either the default /etc/wireguard/wg0.conf or a custom path), reload without disrupting sessions by stripping then syncconf, and tear down optionally saving state first.

```bash
# Bring up an interface from /etc/wireguard/wg0.conf
wg-quick up wg0
wg-quick up /path/to/wgnet0.conf

# Reload without disrupting sessions: strip then syncconf
wg syncconf wgnet0 <(wg-quick strip wgnet0)

# Tear down (optionally saving state first)
wg-quick save wg0
wg-quick down wg0
```

--------------------------------

### Check if key is all zeros

Source: https://github.com/wireguard/wireguard-tools/blob/master/_autodocs/api-reference/encoding.md

Constant-time test whether all 32 bytes are zero. Used by the UAPI get decoder to decide if a received preshared_key counts as 'set'.

```c
bool key_is_zero(const uint8_t key[static WG_KEY_LEN]);
```

--------------------------------

### C: Create, configure, and delete a WireGuard device with error handling

Source: https://github.com/wireguard/wireguard-tools/blob/master/_autodocs/api-reference/embeddable-wg-library.md

Demonstrates creating a device named wg1, setting its listen port to 51820, and deleting it. Checks errno for EEXIST on creation and prints errors using perror for wg_set_device and wg_del_device failures. Note that wg_set_device may return EOPNOTSUPP if the kernel lacks WireGuard support.

```c
/* Create, configure, delete — checking errno on every step */
if (wg_add_device("wg1") < 0 && errno != EEXIST) {
	perror("wg_add_device");
	return 1;
}
wg_device dev = { .name = "wg1" };
dev.flags = WGDEVICE_HAS_LISTEN_PORT;
dev.listen_port = 51820;
if (wg_set_device(&dev) < 0) {
	perror("wg_set_device");   /* e.g. EOPNOTSUPP when the kernel lacks wireguard */
	wg_del_device("wg1");
	return 1;
}
if (wg_del_device("wg1") < 0)
	perror("wg_del_device");
```

--------------------------------

### config_read_init - Initialize config parser context

Source: https://github.com/wireguard/wireguard-tools/blob/master/_autodocs/api-reference/config-parser.md

Initializes a config parsing context. The ctx must be zero-initialized; ctx->device is calloc'd. When append is false, pre-sets WGDEVICE_REPLACE_PEERS | WGDEVICE_HAS_PRIVATE_KEY | WGDEVICE_HAS_FWMARK | WGDEVICE_HAS_LISTEN_PORT so attributes absent from the file are cleared on apply; when true, no flags are pre-set (used by addconf). Returns false (after perror("calloc")) on allocation failure.

```c
bool config_read_init(struct config_ctx *ctx, bool append);
```

--------------------------------

### config_read_finish - Finalize config parsing and return device

Source: https://github.com/wireguard/wireguard-tools/blob/master/_autodocs/api-reference/config-parser.md

Finalizes parsing and returns the fully built struct wgdevice * (caller owns it; release with free_wgdevice). Validates that every parsed peer carries WGPEER_HAS_PUBLIC_KEY; on the first offender prints 'A peer is missing a public key', frees the device, and returns NULL. The context itself is not freed because ctx is typically stack-allocated by the caller.

```c
struct wgdevice *config_read_finish(struct config_ctx *ctx);
```

--------------------------------

### wg set: error handling for malformed allowed-ips

Source: https://github.com/wireguard/wireguard-tools/blob/master/_autodocs/api-reference/wg-set.md

Shows how to handle a malformed allowed-ips value, which causes wg set to abort with exit code 1. The example checks the exit status and prints a diagnostic message.

```bash
# Error handling: a malformed allowed-ip aborts with exit code 1
if ! wg set wg0 peer "$PEER_PUB" allowed-ips 10.1.2.999/24; then
    echo "allowed-ips rejected by wg" >&2
fi
```

--------------------------------

### showconf usage string

Source: https://github.com/wireguard/wireguard-tools/blob/master/_autodocs/api-reference/wg.md

Exact usage string for the showconf subcommand. Requires exactly two arguments: the literal 'showconf' and the WireGuard interface name. If argc != 2, usage is printed to stderr and the command returns 1.

```text
Usage: <prog> showconf <interface>
```

--------------------------------

### C: Handle ipc_set_device failure with strerror

Source: https://github.com/wireguard/wireguard-tools/blob/master/_autodocs/errors.md

Handle failures from the C IPC/embeddable library. Functions return 0 or negative errno; use strerror(-ret) to get the error message. If errno is 0 after a failure, the protocol-level default -EPROTO applies.

```c
int ret = ipc_set_device(dev);
if (ret != 0) {
    fprintf(stderr, "ipc_set_device: %s\n", strerror(-ret));
    exit(1);
}
```

--------------------------------

### wg set: device-level attributes and peer management

Source: https://github.com/wireguard/wireguard-tools/blob/master/_autodocs/api-reference/wg-set.md

Shows how to set device-level attributes like listen-port and private-key, replace a peer with preshared-key, endpoint, persistent-keepalive, and allowed-ips, and perform incremental updates such as modifying allowed-ips, removing a peer, and clearing keys. Uses bash process substitution to avoid exposing keys in argv.

```bash
# Set device-level attributes
wg set wg0 listen-port 51820 private-key <(echo $PRIVATE_KEY)

# Replace a peer, using bash process substitution so keys never hit argv
wg set wg0 peer "$PEER_PUB" \
    preshared-key <(echo "$PSK") \
    endpoint 192.95.5.67:1234 \
    persistent-keepalive 25 \
    allowed-ips 10.192.122.3/32,10.192.124.1/24

# Incremental update: only touch allowed-ips, remove peer, clear keys
wg set wg0 peer "$PEER_PUB" allowed-ips +10.0.0.1/32,-10.192.124.1/24
wg set wg0 peer "$PEER_PUB" remove
wg set wg0 private-key /dev/null peer "$PEER_PUB" preshared-key /dev/null
```

--------------------------------

### Shell: Check wg setconf exit status

Source: https://github.com/wireguard/wireguard-tools/blob/master/_autodocs/errors.md

Check the exit status of the wg command. A non-zero exit status indicates failure; stderr is used as the message channel. The example redirects stderr to a log file and prints its contents on failure.

```bash
if ! wg setconf wg0 /etc/wireguard/wg0.conf 2>err.log; then
    echo "setconf failed: $(cat err.log)"
    exit 1
fi
```

--------------------------------

### show usage string

Source: https://github.com/wireguard/wireguard-tools/blob/master/_autodocs/api-reference/wg.md

Exact usage string printed by show_usage() (src/show.c:203). It lists the target selector and all supported output field selectors.

```text
Usage: <prog> show { <interface> | all | interfaces } [public-key | private-key | listen-port | fwmark | peers | preshared-keys | endpoints | allowed-ips | latest-handshakes | transfer | persistent-keepalive | dump]
```

--------------------------------

### config_read_cmd declaration

Source: https://github.com/wireguard/wireguard-tools/blob/master/_autodocs/api-reference/config-parser.md

Declares the command-line token parser for the wg set grammar. The argv vector must start after the interface name (argv + 2 as invoked from set_main). On error, prints 'Invalid argument: <token>' and returns NULL after freeing the device; on success returns the device with flags set as described for set in wg-set.md.

```c
struct wgdevice *config_read_cmd(const char *argv[], int argc);
```

--------------------------------

### config_read_init

Source: https://github.com/wireguard/wireguard-tools/blob/master/_autodocs/api-reference/config-parser.md

Initializes a configuration parsing context. It allocates the device structure and optionally pre-sets flags to clear absent attributes on apply.

```APIDOC
## config_read_init

### Description
Initializes a configuration parsing context. It allocates the device structure and optionally pre-sets flags to clear absent attributes on apply.

### Function Signature
```c
bool config_read_init(struct config_ctx *ctx, bool append);
```

### Parameters
- **ctx** (struct config_ctx *) - Required - Zero-initialized; `ctx->device` is calloc'd.
- **append** (bool) - Required - When false, pre-sets `WGDEVICE_REPLACE_PEERS | WGDEVICE_HAS_PRIVATE_KEY | WGDEVICE_HAS_FWMARK | WGDEVICE_HAS_LISTEN_PORT` so attributes absent from the file are cleared on apply; when true, no flags are pre-set (used by `addconf`).

### Return Value
Returns `false` (after `perror("calloc")`) on allocation failure.

```

--------------------------------

### C: Retrieve and print WireGuard peers using wg_get_device

Source: https://github.com/wireguard/wireguard-tools/blob/master/_autodocs/api-reference/embeddable-wg-library.md

Shows how to fetch a WireGuard device by name, iterate over its peers, and print each peer's public key and received byte count. Returns 1 and prints an error to stderr if wg_get_device fails. Requires including wireguard.h and linking against the wireguard-tools library.

```c
#include <stdio.h>
#include "wireguard.h"

int main(void)
{
	wg_device *dev = NULL;
	int ret = wg_get_device(&dev, "wg0");
	if (ret < 0) {
		fprintf(stderr, "wg_get_device: %s\n", strerror(-ret));
		return 1;
	}
	wg_peer *peer;
	wg_for_each_peer(dev, peer) {
		wg_key_b64_string b64;
		wg_key_to_base64(b64, peer->public_key);
		printf("peer: %s (rx=%llu)\n", b64, (unsigned long long)peer->rx_bytes);
	}
	wg_free_device(dev);
	return 0;
}
```

--------------------------------

### config_read_line - Process a configuration line

Source: https://github.com/wireguard/wireguard-tools/blob/master/_autodocs/api-reference/config-parser.md

Processes a single line of configuration. Truncates at the first '#' (comment), strips whitespace, and dispatches non-empty results to process_line. Section headers [Interface] and [Peer] (case-insensitive) switch the active section; a [Peer] header allocates a new struct wgpeer and links it onto the list. Key matching is strncasecmp-based with exact forms; unrecognized lines print 'Line unrecognized: `<line>'' and return false, freeing the device and leaving ctx->device stale/NULL.

```c
bool config_read_line(struct config_ctx *ctx, const char *line);
```

--------------------------------

### Iteration macros for containers (src/containers.h)

Source: https://github.com/wireguard/wireguard-tools/blob/master/_autodocs/types.md

Macros to iterate over peers in a device and allowed IPs in a peer. Use for_each_wgpeer and for_each_wgallowedip for internal container traversal.

```c
/* src/containers.h */
#define for_each_wgpeer(__dev, __peer) for ((__peer) = (__dev)->first_peer; (__peer); (__peer) = (__peer)->next_peer)
#define for_each_wgallowedip(__peer, __allowedip) for ((__allowedip) = (__peer)->first_allowedip; (__allowedip); (__allowedip) = (__allowedip)->next_allowedip)
```

--------------------------------

### pubkey usage string

Source: https://github.com/wireguard/wireguard-tools/blob/master/_autodocs/api-reference/wg-keygen.md

Exact usage string for the pubkey subcommand. If argc is not 1, the usage is printed to stderr and the program returns 1.

```text
Usage: <prog> pubkey
```

--------------------------------

### Iteration macros for public API (wireguard.h)

Source: https://github.com/wireguard/wireguard-tools/blob/master/_autodocs/types.md

Public iteration macros for device names, peers, and allowed IPs. wg_for_each_device_name iterates over a null-separated list of names; the others traverse linked lists.

```c
/* wireguard.h */
#define wg_for_each_device_name(__names, __name, __len) for ((__name) = (__names), (__len) = 0; ((__len) = strlen(__name)); (__name) += (__len) + 1)
#define wg_for_each_peer(__dev, __peer) for ((__peer) = (__dev)->first_peer; (__peer); (__peer) = (__peer)->next_peer)
#define wg_for_each_allowedip(__peer, __allowedip) for ((__allowedip) = (__peer)->first_allowedip; (__allowedip); (__allowedip) = (__allowedip)->next_allowedip)
```

--------------------------------

### wg_free_device

Source: https://github.com/wireguard/wireguard-tools/blob/master/_autodocs/api-reference/embeddable-wg-library.md

Recursively frees AllowedIPs, peers, and the device. NULL-safe.

```APIDOC
## `wg_free_device`

### Description
Recursively frees AllowedIPs, peers, and the device. NULL-safe.

### Function Signature
```c
void wg_free_device(wg_device *dev);
```

### Parameters
- **dev** (`wg_device *`) - Required - Device to free.
```

--------------------------------

### Key helper functions

Source: https://github.com/wireguard/wireguard-tools/blob/master/_autodocs/api-reference/embeddable-wg-library.md

Functions for key conversion, zero-check, and generation. wg_key_from_base64 returns -EINVAL on invalid input; generation functions use random bytes and clamp as noted.

```c
void wg_key_to_base64(wg_key_b64_string base64, const wg_key key);
int wg_key_from_base64(wg_key key, const wg_key_b64_string base64);
bool wg_key_is_zero(const wg_key key);
void wg_generate_public_key(wg_key public_key, const wg_key private_key);
void wg_generate_private_key(wg_key private_key);
void wg_generate_preshared_key(wg_key preshared_key);
```

--------------------------------

### Reusing wg set grammar with config_read_cmd

Source: https://github.com/wireguard/wireguard-tools/blob/master/_autodocs/api-reference/config-parser.md

Builds an argv vector to reuse the wg set grammar programmatically. On failure, a diagnostic is already printed to stderr; on success, set the device name and pass to ipc_set_device(). Remember to free with free_wgdevice.

```c
/* Reuse the wg set grammar programmatically: build an argv vector. */
const char *tokens[] = {
	"peer", "xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg=",
	"endpoint", "192.95.5.67:1234",
	"allowed-ips", "10.192.122.3/32,10.192.124.1/24"
};
struct wgdevice *dev = config_read_cmd(tokens,
	(int)(sizeof(tokens) / sizeof(tokens[0])));
if (!dev) {
	/* a diagnostic was already printed to stderr */
	exit(1);
}
dev->name[0] = 'w'; dev->name[1] = 'g'; dev->name[2] = '0'; dev->name[3] = '\0';
/* ... pass to ipc_set_device() ... */
free_wgdevice(dev);
```

--------------------------------

### Derive public key from private key with wg pubkey

Source: https://github.com/wireguard/wireguard-tools/blob/master/_autodocs/api-reference/wg-keygen.md

Classic pipeline to generate a private key, save it, and derive the corresponding public key. The private key is clamped by genkey, and pubkey derives the public key in place.

```bash
# Derive a public key from a private key (classic pipeline from wg(8))
umask 077
wg genkey | tee private.key | wg pubkey > public.key
```

--------------------------------

### wg_free_device - Free device structure

Source: https://github.com/wireguard/wireguard-tools/blob/master/_autodocs/api-reference/embeddable-wg-library.md

Recursively frees AllowedIPs, peers, and the device. NULL-safe.

```c
void wg_free_device(wg_device *dev);
```

--------------------------------

### genkey/genpsk usage string

Source: https://github.com/wireguard/wireguard-tools/blob/master/_autodocs/api-reference/wg-keygen.md

Exact usage string for the genkey and genpsk subcommands. If argc is not 1, the usage is printed to stderr and the program returns 1.

```text
Usage: <prog> genkey
Usage: <prog> genpsk
```
Tokens:
Raw