Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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:

       o      PrivateKey  --  a	base64 private key generated by	wg genkey. Re-
	      quired.

       o      ListenPort -- a 16-bit port  for	listening.  Optional;  if  not
	      specified, chosen	randomly.

       o      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:

       o      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.

       o      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.

       o      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.

       o      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.

       o      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  userspace implementations, it is customary to set the LOG_LEVEL en-
       vironment variable to debug.

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://www.freebsd.org/cgi/man.cgi?query=wg&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help