Provided by: wireguard-tools_1.0.20210914-1ubuntu4_amd64 bug

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 configuration 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  aspects  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, <interface> 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,  persistent-
              keepalive.

       showconf <interface>
              Shows  the  current  configuration  of  <interface>  in  the  format  described  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>.  Multiple  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  preshared-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  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 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 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; 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 efficient than setconf, but has  the  benefit  of  not
              disrupting  current peer sessions. The contents of <configuration-filename> must be
              in the format described by CONFIGURATION FILE FORMAT below.

       genkey Generates a random private key in base64 and prints it to standard 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  output  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 specified, 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. Required.

       •      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 allowed 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 addresses. 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 authenticated 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 supports dynamic debugging, debugging
       information can be written into dmesg(1) by running as root:

           #     modprobe     wireguard     &&     echo      module      wireguard      +p      >
       /sys/kernel/debug/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 environment 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, something 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-permanent  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/⟩.