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

FreeBSD Manual Pages

  
 
  

home | help
WG(4)			    Kernel Interfaces Manual			 WG(4)

NAME
       wg -- WireGuard protocol	driver

SYNOPSIS
       To  compile  this  driver into the kernel, place	the following lines in
       your kernel configuration file:

	     device wg

       Alternatively, to load the driver as a module at	boot time,  place  the
       following line in loader.conf(5):

	     if_wg_load="YES"

DESCRIPTION
       The wg driver provides Virtual Private Network (VPN) interfaces for the
       secure exchange of layer	3 traffic with other WireGuard peers using the
       WireGuard protocol.

       A  wg interface recognizes one or more peers, establishes a secure tun-
       nel with	each on	demand,	and tracks each	peer's UDP  endpoint  for  ex-
       changing	encrypted traffic with.

       The  interfaces can be created at runtime using the ifconfig wgN	create
       command.	 The interface itself can be configured	with wg(8).

       The following glossary provides a brief overview	of WireGuard terminol-
       ogy:

	  Peer	  Peers	exchange IPv4 or IPv6  traffic	over  secure  tunnels.
		  Each wg interface may	be configured to recognise one or more
		  peers.

	  Key	  Each	peer uses its private key and corresponding public key
		  to identify itself to	others.	 A peer	configures a wg	inter-
		  face with its	own private key	and with the  public  keys  of
		  its peers.

	  Pre-shared key
		  In  addition	to the public keys, each peer pair may be con-
		  figured with a unique	pre-shared  symmetric  key.   This  is
		  used	in  their handshake to guard against future compromise
		  of the peers'	encrypted tunnel if an attack on their Diffie-
		  Hellman exchange becomes feasible.  It is optional, but rec-
		  ommended.

	  Allowed IP addresses
		  A single wg interface	may maintain concurrent	 tunnels  con-
		  necting  diverse  networks.	The interface therefore	imple-
		  ments	rudimentary routing and	reverse-path  filtering	 func-
		  tions	for its	tunneled traffic.  These functions reference a
		  set  of  allowed  IP	address	ranges configured against each
		  peer.

		  The interface	will route outbound tunneled  traffic  to  the
		  peer	configured  with the most specific matching allowed IP
		  address range, or drop it if no such match exists.

		  The interface	will accept tunneled  traffic  only  from  the
		  peer	configured  with the most specific matching allowed IP
		  address range	for the	incoming traffic, or  drop  it	if  no
		  such	match  exists.	 That is, tunneled traffic routed to a
		  given	peer cannot return through another peer	of the same wg
		  interface.  This ensures that	peers  cannot  spoof  one  an-
		  other's traffic.

	  Handshake
		  Two  peers handshake to mutually authenticate	each other and
		  to establish a shared	series of secret ephemeral  encryption
		  keys.	 Either	peer may initiate a handshake.	Handshakes oc-
		  cur  only when there is traffic to send, and recur every two
		  minutes during transfers.

	  Connectionless
		  Due to the handshake behavior, there is no connected or dis-
		  connected state.

   Keys
       Private keys for	WireGuard can be generated from	any  sufficiently  se-
       cure  random  source.   The Curve25519 keys and the pre-shared keys are
       both 32 bytes long and are commonly encoded in base64 for ease of use.

       Keys can	be generated with wg(8)	as follows:

	     $ wg genkey

       Although	a valid	Curve25519 key must have 5 bits	set to	specific  val-
       ues,  this  is  done  by	the interface and so it	will accept any	random
       32-byte base64 string.

NETMAP
       netmap(4) applications may open a WireGuard interface in	emulated mode.
       The netmap application will receive decrypted,  unencapsulated  packets
       prepended  by a dummy Ethernet header.  The Ethertype field will	be one
       of ETHERTYPE_IP or ETHERTYPE_IPV6 depending on the  address  family  of
       the  packet.   Packets  transmitted by the application should similarly
       begin with a dummy Ethernet header; this	header will be stripped	before
       the packet is encrypted and tunneled.

EXAMPLES
       Create a	wg interface and set random private key.

	     # ifconfig	wg0 create
	     # wg genkey | wg set wg0 listen-port 54321	private-key /dev/stdin

       Retrieve	the associated public key from a wg interface.

	     $ wg show wg0 public-key

       Connect to a specific endpoint using its	public-key and set the allowed
       IP address

	     # wg set wg0 peer '7lWtsDdqaGB3EY9WNxRN3hVaHMtu1zXw71+bOjNOVUw=' endpoint 10.0.1.100:54321	allowed-ips 192.168.2.100/32

       Remove a	peer

	     # wg set wg0 peer '7lWtsDdqaGB3EY9WNxRN3hVaHMtu1zXw71+bOjNOVUw=' remove

DIAGNOSTICS
       The wg interface	supports runtime debugging, which can be enabled with:

	     ifconfig wgN debug

       Some common error messages include:

       Handshake for peer X did	not complete after 5 seconds, retrying	Peer X
       did not reply to	our initiation packet, for example because:

          The peer does not have the local interface configured  as  a	 peer.
	   Peers must be able to mutually authenticate each other.

          The peer endpoint IP	address	is incorrectly configured.

          There are firewall rules preventing communication between hosts.

       Invalid	handshake  initiation  The incoming handshake packet could not
       be processed.  This is likely due to the	local interface	not containing
       the correct public key for the peer.

       Invalid initiation MAC  The incoming handshake initiation packet	had an
       invalid MAC.  This is likely because  the  initiation  sender  has  the
       wrong public key	for the	handshake receiver.

       Packet  has unallowed src IP from peer X	 After decryption, an incoming
       data packet has a source	IP address that	is not assigned	to the allowed
       IPs of Peer X.

SEE ALSO
       inet(4),	ip(4),	ipsec(4),  netintro(4),	 netmap(4),  ovpn(4),  ipf(5),
       pf.conf(5), ifconfig(8),	ipfw(8), wg(8)

       WireGuard whitepaper, https://www.wireguard.com/papers/wireguard.pdf.

HISTORY
       The wg device driver first appeared in FreeBSD 13.2.

AUTHORS
       The   wg	  device   driver   was	  written   by	 Jason	 A.  Donenfeld
       <Jason@zx2c4.com>,  Matt	 Dunwoodie  <ncon@nconroy.net>,	  Kyle	 Evans
       <kevans@FreeBSD.org>, and Matt Macy <mmacy@FreeBSD.org>.

       This  manual  page was written by Gordon	Bergling <gbe@FreeBSD.org> and
       is  based  on  the  OpenBSD  manual  page  written  by	David	Gwynne
       <dlg@openbsd.org>.

FreeBSD	14.3		       February	12, 2025			 WG(4)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=wg&sektion=4&manpath=FreeBSD+14.3-RELEASE+and+Ports>

home | help