diff options
Diffstat (limited to 'src/tools/wg.8')
| -rw-r--r-- | src/tools/wg.8 | 194 |
1 files changed, 194 insertions, 0 deletions
diff --git a/src/tools/wg.8 b/src/tools/wg.8 new file mode 100644 index 0000000..4ee5027 --- /dev/null +++ b/src/tools/wg.8 @@ -0,0 +1,194 @@ +.TH WG 8 "2015 August 13" ZX2C4 "WireGuard" + +.SH NAME +wg - set and retrieve configuration of WireGuard interfaces + +.SH SYNOPSIS +.B wg +[ +.I COMMAND +] [ +.I OPTIONS +]... [ +.I ARGS +]... + +.SH DESCRIPTION + +.B wg +is the configuration utility for getting and setting the configuration of +WireGuard tunnel interfaces. The interfaces themselves can be added and removed +using +.BR ip-link (8) +and their IP addresses and routing tables can be set using +.BR ip-address (8) +and +.BR ip-route (8). +The +.B wg +utility provides a series of sub-commands for changing WireGuard-specific +aspects of WireGuard interfaces. + +If no COMMAND is specified, COMMAND defaults to +.BR show . +Sub-commands that take an INTERFACE must be passed a WireGuard interface. + +.SH COMMANDS + +.TP +\fBshow\fP { \fI<interface>\fP | \fIall\fP | \fIinterfaces\fP } [\fIpublic-key\fP | \fIprivate-key\fP | \fIpreshared-key\fP | \fIlisten-port\fP | \fIpeers\fP | \fIendpoints\fP | \fIallowed-ips\fP | \fIlatest-handshake\fP | \fIbandwidth\fP] +Shows current WireGuard configuration of specified \fI<interface>\fP. +If no \fI<interface>\fP is specified, \fI<interface>\fP defaults to \fIall\fP. +If \fIinterfaces\fP is specified, prints a list of all WireGuard interfaces, +one per line, and quit. 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. +.TP +\fBshowconf\fP \fI<interface>\fP +Shows the current configuration of \fI<interface>\fP in the format described +by \fICONFIGURATION FILE FORMAT\fP below. +.TP +\fBset\fP \fI<interface>\fP [\fIlisten-port\fP \fI<port>\fP] [\fIprivate-key\fP \fI<file-path>\fP] [\fIpreshared-key\fP \fI<file-path>\fP] [\fIpeer\fP \fI<base64-public-key>\fP [\fIremove\fP] [\fIendpoint\fP \fI<ip>:<port>\fP] [\fIallowed-ips\fP \fI<ip1>/<cidr1>\fP[,\fI<ip2>/<cidr2>\fP]...] ]... +Sets configuration values for the specified \fI<interface>\fP. Multiple +\fIpeer\fPs may be specified, and if the \fIremove\fP argument is given +for a peer, that peer is removed, not configured. If \fIlisten-port\fP +is not specified, the port will be automatically generated when the +interface comes up. Both \fIprivate-key\fP and \fIpreshared-key\fP must +be a files, for security reasons, but if you're using +.BR bash (1), +you may safely pass in a string by specifying as \fIprivate-key\fP or +\fIpreshared-key\fP the expression: <(echo PRIVATEKEYSTRING). If +\fI/dev/null\fP is specified as the filename for either \fIprivate-key\fP or +\fIpreshared-key\fP, the key is removed from the device. The use of +\fIpreshared-key\fP is optional, and may be omitted; it adds an additional +layer of symmetric-key cryptography to be mixed into the already existing +public-key cryptography, for post-quantum resistance. If \fIallowed-ips\fP +is specified, but the value is the empty string, all allowed ips are removed +from the peer. +.TP +\fBsetconf\fP \fI<interface>\fP \fI<configuration-filename>\fP +Sets the current configuration of \fI<interface>\fP to the contents of +\fI<configuration-filename>\fP, which must be in the format described +by \fICONFIGURATION FILE FORMAT\fP below. +.TP +\fBaddconf\fP \fI<interface>\fP \fI<configuration-filename>\fP +Appends the contents of \fI<configuration-filename>\fP, which must +be in the format described by \fICONFIGURATION FILE FORMAT\fP below, +to the current configuration of \fI<interface>\fP. +.TP +\fBgenkey\fP +Generates a random \fIprivate\fP key in base64 and prints it to +standard output. +.TP +\fBgenpsk\fP +Generates a random \fIpreshared\fP key in base64 and prints it to +standard output. +.TP +\fBpubkey\fP +Calculates a \fIpublic\fP key and prints it in base64 to standard +output from a corresponding \fIprivate\fP key (generated with +\fIgenkey\fP) given in base64 on standard input. + +A private key and a corresponding public key may be generated at once by calling: +.br + $ umask 077 +.br + $ wg genkey | tee private.key | wg pubkey > public.key +.TP +\fBhelp\fP +Show usage message. + +.SH CONFIGURATION FILE FORMAT +The configuration file format is based on \fIINI\fP. There are two top level sections +-- \fIInterface\fP and \fIPeer\fP. Multiple \fIPeer\fP sections may be specified, but +only one \fIInterface\fP section may be specified. + +.P +The \fIInterface\fP section contains two fields: +.IP \(bu +PrivateKey \(em a base64 private key generated by \fIwg genkey\fP. Required. +.IP \(bu +PresharedKey \(em a base64 preshared key generated by \fIwg genpsk\fP. 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. +.IP \(bu +ListenPort \(em a 16-bit port for listening. Optional; if not specified, +automatically generated based on interface name. +.P +The \fIPeer\fP sections contain three fields each: +.IP \(bu +PublicKey \(em a base64 public key calculated by \fIwg pubkey\fP from a +private key, and usually transmitted out of band to the author of the +configuration file. Required. +.IP \(bu +AllowedIPs \(em a comma-separated list of IP (v4 or v6) addresses with +CIDR masks. The catch-all \fI0.0.0.0/0\fP may be specified for matching +all IPv4 addresses, and \fI::/0\fP may be specified for matching all +IPv6 addresses. Required. +.IP \(bu +Endpoint \(em an endpoint IP or hostname, followed by a comma, and then a +port number. Optional. + +.SH CONFIGURATION FILE FORMAT EXAMPLE +This example may be used as a model for writing configuration files. +Note that not all keys are required. + + [Interface] +.br + PrivateKey = yAnz5TF+lXXJte14tji3zlMNq+hd2rYUIgJBgB3fBmk= +.br + ListenPort = 41414 +.br + +.br + [Peer] +.br + PublicKey = xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg= +.br + Endpoint = 192.95.5.67:1234 +.br + AllowedIPs = 10.192.122.3/32, 10.192.124.1/24 +.br + +.br + [Peer] +.br + PublicKey = TrMvSoP4jYQlY6RIzBgbssQqY3vxI2Pi+y71lOWWXX0= +.br + Endpoint = [2607:5300:60:6b0::c05f:543]:2468 +.br + AllowedIPs = 10.192.122.4/32, 192.168.0.0/16 +.br + +.br + [Peer] +.br + PublicKey = gN65BkIKy1eCE9pP1wdc8ROUtkHLF2PfAqYdyYBz6EA= +.br + Endpoint = test.wireguard.io:18981 +.br + AllowedIPs = 10.10.10.230/32 + +.SH ENVIRONMENT VARIABLES +.TP +.I WG_COLOR_MODE +If set to \fIalways\fP, always print ANSI colorized output. If set to \fInever\fP, never print ANSI colorized output. If set to \fIauto\fP, something invalid, or unset, then print ANSI colorized output only when writing to a TTY. + +.SH SEE ALSO +.BR ip (8), +.BR ip-link (8), +.BR ip-address (8), +.BR ip-route (8). + +.SH AUTHOR +.B wg +was written by +.MT Jason@zx2c4.com +Jason A. Donenfeld +.ME . +For updates and more information, a project page is available on the +.UR http://\:www.wireguard.io/ +World Wide Web +.UE . |