FreeBSD Manual Pages
WG(8) WireGuard WG(8) NAME wg - set and retrieve configuration of WireGuard interfaces SYNOPSIS wg [ COMMAND ] [ OPTIONS ]... [ ARGS ]... DESCRIPTION wg is the configuration utility for getting and setting the configura- tion of WireGuard tunnel interfaces. The interfaces themselves can be added and removed using ip-link(8) and their IP addresses and routing tables can be set using ip-address(8) and ip-route(8). The wg utility provides a series of sub-commands for changing WireGuard-specific as- pects of WireGuard interfaces. If no COMMAND is specified, COMMAND defaults to show. Sub-commands that take an INTERFACE must be passed a WireGuard interface. COMMANDS show { <interface> | all | interfaces } [public-key | private-key | listen-port | fwmark | peers | preshared-keys | endpoints | allowed-ips | latest-handshakes | persistent-keepalive | transfer | dump] Shows current WireGuard configuration and runtime information of specified <interface>. If no <interface> is specified, <inter- face> defaults to all. If interfaces is specified, prints a list of all WireGuard interfaces, one per line, and quits. If no options are given after the interface specification, then prints a list of all attributes in a visually pleasing way meant for the terminal. Otherwise, prints specified information grouped by newlines and tabs, meant to be used in scripts. For this script- friendly display, if all is specified, then the first field for all categories of information is the interface name. If dump is specified, then several lines are printed; the first contains in order separated by tab: private-key, public-key, listen-port, fwmark. Subsequent lines are printed for each peer and contain in order separated by tab: public-key, preshared-key, endpoint, allowed-ips, latest-handshake, transfer-rx, transfer-tx, persis- tent-keepalive. showconf <interface> Shows the current configuration of <interface> in the format de- scribed by CONFIGURATION FILE FORMAT below. set <interface> [listen-port <port>] [fwmark <fwmark>] [private-key <file-path>] [peer <base64-public-key> [remove] [preshared-key <file- path>] [endpoint <ip>:<port>] [persistent-keepalive <interval seconds>] [allowed-ips <ip1>/<cidr1>[,<ip2>/<cidr2>]...] ]... Sets configuration values for the specified <interface>. Multi- ple peers may be specified, and if the remove argument is given for a peer, that peer is removed, not configured. If listen-port is not specified, or set to 0, the port will be chosen randomly when the interface comes up. Both private-key and preshared-key must be files, because command line arguments are not considered private on most systems but if you are using bash(1), you may safely pass in a string by specifying as private-key or pre- shared-key the expression: <(echo PRIVATEKEYSTRING). If /dev/null or another empty file is specified as the filename for either private-key or preshared-key, the key is removed from the device. The use of preshared-key is optional, and may be omit- ted; it adds an additional layer of symmetric-key cryptography to be mixed into the already existing public-key cryptography, for post-quantum resistance. If allowed-ips is specified, but the value is the empty string, all allowed ips are removed from the peer. The use of persistent-keepalive is optional and is by default off; setting it to 0 or "off" disables it. Otherwise it represents, in seconds, between 1 and 65535 inclusive, how often to send an authenticated empty packet to the peer, for the pur- pose of keeping a stateful firewall or NAT mapping valid persis- tently. For example, if the interface very rarely sends traffic, but it might at anytime receive traffic from a peer, and it is behind NAT, the interface might benefit from having a persistent keepalive interval of 25 seconds; however, most users will not need this. The use of fwmark is optional and is by default off; setting it to 0 or "off" disables it. Otherwise it is a 32-bit fwmark for outgoing packets and may be specified in hexadecimal by prepending "0x". setconf <interface> <configuration-filename> Sets the current configuration of <interface> to the contents of <configuration-filename>, which must be in the format described by CONFIGURATION FILE FORMAT below. addconf <interface> <configuration-filename> Appends the contents of <configuration-filename>, which must be in the format described by CONFIGURATION FILE FORMAT below, to the current configuration of <interface>. syncconf <interface> <configuration-filename> Like setconf, but reads back the existing configuration first and only makes changes that are explicitly different between the configuration file and the interface. This is much less effi- cient than setconf, but has the benefit of not disrupting cur- rent peer sessions. The contents of <configuration-filename> must be in the format described by CONFIGURATION FILE FORMAT be- low. genkey Generates a random private key in base64 and prints it to stan- dard output. genpsk Generates a random preshared key in base64 and prints it to standard output. pubkey Calculates a public key and prints it in base64 to standard out- put from a corresponding private key (generated with genkey) given in base64 on standard input. A private key and a corresponding public key may be generated at once by calling: $ umask 077 $ wg genkey | tee private.key | wg pubkey > public.key help Shows usage message. CONFIGURATION FILE FORMAT The configuration file format is based on INI. There are two top level sections -- Interface and Peer. Multiple Peer sections may be speci- fied, but only one Interface section may be specified. The Interface section may contain the following fields: • PrivateKey -- a base64 private key generated by wg genkey. Re- quired. • ListenPort -- a 16-bit port for listening. Optional; if not specified, chosen randomly. • FwMark -- a 32-bit fwmark for outgoing packets. If set to 0 or "off", this option is disabled. May be specified in hexadecimal by prepending "0x". Optional. The Peer sections may contain the following fields: • PublicKey -- a base64 public key calculated by wg pubkey from a private key, and usually transmitted out of band to the author of the configuration file. Required. • PresharedKey -- a base64 preshared key generated by wg genpsk. Optional, and may be omitted. This option adds an additional layer of symmetric-key cryptography to be mixed into the already existing public-key cryptography, for post-quantum resistance. • AllowedIPs -- a comma-separated list of IP (v4 or v6) addresses with CIDR masks from which incoming traffic for this peer is al- lowed and to which outgoing traffic for this peer is directed. The catch-all 0.0.0.0/0 may be specified for matching all IPv4 addresses, and ::/0 may be specified for matching all IPv6 ad- dresses. May be specified multiple times. • Endpoint -- an endpoint IP or hostname, followed by a colon, and then a port number. This endpoint will be updated automatically to the most recent source IP address and port of correctly au- thenticated packets from the peer. Optional. • PersistentKeepalive -- a seconds interval, between 1 and 65535 inclusive, of how often to send an authenticated empty packet to the peer for the purpose of keeping a stateful firewall or NAT mapping valid persistently. For example, if the interface very rarely sends traffic, but it might at anytime receive traffic from a peer, and it is behind NAT, the interface might benefit from having a persistent keepalive interval of 25 seconds. If set to 0 or "off", this option is disabled. By default or when unspecified, this option is off. Most users will not need this. Optional. CONFIGURATION FILE FORMAT EXAMPLE This example may be used as a model for writing configuration files, following an INI-like syntax. Characters after and including a '#' are considered comments and are thus ignored. [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 [Peer] PublicKey = TrMvSoP4jYQlY6RIzBgbssQqY3vxI2Pi+y71lOWWXX0= Endpoint = [2607:5300:60:6b0::c05f:543]:2468 AllowedIPs = 10.192.122.4/32, 192.168.0.0/16 [Peer] PublicKey = gN65BkIKy1eCE9pP1wdc8ROUtkHLF2PfAqYdyYBz6EA= Endpoint = test.wireguard.com:18981 AllowedIPs = 10.10.10.230/32 DEBUGGING INFORMATION Sometimes it is useful to have information on the current runtime state of a tunnel. When using the Linux kernel module on a kernel that sup- ports dynamic debugging, debugging information can be written into dmesg(1) by running as root: # modprobe wireguard && echo module wireguard +p > /sys/kernel/de- bug/dynamic_debug/control On OpenBSD and FreeBSD, debugging information can be written into dmesg(1) on a per-interface basis by using ifconfig(1): # ifconfig wg0 debug On userspace implementations, it is customary to set the LOG_LEVEL en- vironment variable to verbose. ENVIRONMENT VARIABLES WG_COLOR_MODE If set to always, always print ANSI colorized output. If set to never, never print ANSI colorized output. If set to auto, some- thing invalid, or unset, then print ANSI colorized output only when writing to a TTY. WG_HIDE_KEYS If set to never, then the pretty-printing show sub-command will show private and preshared keys in the output. If set to always, something invalid, or unset, then private and preshared keys will be printed as "(hidden)". WG_ENDPOINT_RESOLUTION_RETRIES If set to an integer or to infinity, DNS resolution for each peer's endpoint will be retried that many times for non-perma- nent errors, with an increasing delay between retries. If unset, the default is 15 retries. SEE ALSO wg-quick(8), ip(8), ip-link(8), ip-address(8), ip-route(8). AUTHOR wg was written by Jason A. Donenfeld <Jason@zx2c4.com>. For updates and more information, a project page is available on the World Wide Web <https://www.wireguard.com/>. ZX2C4 2015 August 13 WG(8)
NAME | SYNOPSIS | DESCRIPTION | COMMANDS | CONFIGURATION FILE FORMAT | CONFIGURATION FILE FORMAT EXAMPLE | DEBUGGING INFORMATION | ENVIRONMENT VARIABLES | SEE ALSO | AUTHOR
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=wg&sektion=8&manpath=FreeBSD+14.3-RELEASE>