View source for WireGuard

{{InfoBox stack
|{{InfoBox homepage|https://www.wireguard.io/|header=true}}
|{{InfoBox package|net-vpn/wireguard-tools}}
|{{InfoBox gitweb|https://git.zx2c4.com/wireguard-linux|raw=true}}
}}

'''WireGuard''' is [[Article description::a modern, simple, and secure VPN that utilizes state-of-the-art cryptography.]] Considered an alternative to [[OpenVPN]], it can be used to create secure connections. Its goals are to be fast, simple, lean, and easy to configure. Wireguard consists of two components: userspace tools and a kernel module.

Wireguard is written and maintained by {{Dev|zx2c4}}, a Gentoo developer.

Official and potentially more up-to-date installation instructions can be [https://www.wireguard.io/install/ found upstream].

== Installation ==

=== Kernel ===

==== Kernels less than 5.6 ====

Linux kernels less than 5.6 (<=5.5) did not include Wireguard as a feature in the upstream kernel code. Adding Wireguard support to these (older) kernels is possible via additional modules emerged below.

Attempting to add WireGuard support without having a few specific kernel symbols enabled will cause the emerge to fail. A few of the symbols are dependencies and can only be set by setting other options. Perform the necessary work to have the following symbols enabled before moving on to the next section:

* <var>CONFIG_NET</var> - For basic networking support.
* <var>CONFIG_INET</var> - For basic IP support.
* <var>CONFIG_NET_UDP_TUNNEL</var> - For sending and receiving UDP packets.
* <var>CONFIG_NF_CONNTRACK</var> - For determining the source address when constructing ICMP packets.
* <var>CONFIG_NETFILTER_XT_MATCH_HASHLIMIT</var> - For ratelimiting when under DoS attacks.
* <var>CONFIG_IP6_NF_IPTABLES</var> - Only if using <var>CONFIG_IPV6</var> for ratelimiting when under DoS attacks.
* <var>CONFIG_CRYPTO_BLKCIPHER</var> - For doing scatter-gather I/O.
* <var>CONFIG_PADATA</var> - For parallel crypto (only available on multi-core machines).<ref>https://www.wireguard.io/compilation/#kernel-requirements</ref>

{{KernelBox|title=Enable kernel support for WireGuard<ref>https://www.wireguard.io/compilation/#kernel-requirements</ref>|1=
[*] Networking support -->
    Networking options -->
        [*] TCP/IP networking
        [*]   IP: Foo (IP protocols) over UDP
        [*] Network packet filtering framework (Netfilter) -->
            [*] Advanced netfilter configuration
            Core Netfilter Configuration -->
                [*] Netfilter connection tracking support
                [*] Netfilter Xtables support
                [*]   "hashlimit" match support
            [*] IPv6: Netfilter Configuration (only if using IPv6)
[*] Cryptographic API -->
    [*] Cryptographic algorithm manager
    [*] Parallel crypto engine
}}

==== Kernel 5.6 and higher ====

Starting with kernel 5.6, Wireguard is included in the upstream kernel sources. It is enabled via the following menuconfig option:

{{KernelBox|title=Enable <var>CONFIG_WIREGUARD</var>|1=
Device Drivers  --->
    [*] Network device support  --->
        [*] Network core driver support
        <*>   WireGuard secure network tunnel
}}

[https://gitlab.com/vitaly-zdanevich-configs/linux-kernel-thinkpad-t430/-/blob/e0190d62ab1c0f798e6e98b742578c2ffec9899e/.config Working kernel config].

=== USE flags ===

{{USEflag|package=net-vpn/wireguard-tools}}

=== Emerge ===

Install the wireguard-tools package to generate encryption keys and manage Wireguard interfaces:

{{Emerge|net-vpn/wireguard-tools}}

==== Less than 5.6 ====

For Linux kernels less than 5.6 also install the modules:

{{Emerge|net-vpn/wireguard-modules}}

== Configuration ==

=== Kernel module loading ===

{{Note|If wireguard support is added to the kernel as a module, configuring a wireguard interface should load the wireguard kernel module automatically, so there may be no need to set it to load in {{Path|/etc/modules-load.d/}}.}}

If WireGuard support has been added as a module, it may be necessary to instruct the selected init system to load the WireGuard kernel modules when the system boots.

Create a new file in the {{Path|/etc/modules-load.d/}} directory in order to instruct the module loading service to get the module loaded on boot:

{{FileBox|filename=/etc/modules-load.d/wireguard.conf|1=
wireguard
}}

Or if VPN access is not needed very often, load kernel module manually:

{{RootCmd|modprobe wireguard}}

Loaded modules can be reviewed with {{c|lsmod}}.

=== Files ===

==== wg.conf ====

A WireGuard configuration file (the first of which is normally named {{Path|wg0.conf}}) can be written as outlined in the man page. Review the CONFIGURATION FILE FORMAT and CONFIGURATION FILE FORMAT EXAMPLE sections in {{c|man 8 wg}}:

{{Cmd|man 8 wg}}

As mentioned in the man page, WireGuard configuration files are defined in the INI format. A typical configuration file looks something like the following:

{{FileBox|filename=wg0.conf|title=Wireguard configuration file example|lang=ini|1=
[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
}}

== Usage ==

=== Generate a keypair ===

Before using WireGuard a keypair has to be generated. This can be accomplished using {{c|wg(8)}}:

{{Cmd|$(umask 077; wg genkey {{!}} tee privatekey {{!}} wg pubkey > publickey)}}

=== Network management methods ===

Various [[network management]] methods are available to supervise Wireguard tunnels.

==== wg-quick ====

Configuration can be automated using the {{c|wg-quick}} utility, which will create tunnels using configuration files in the {{Path|/etc/wireguard}} file:

{{RootCmd|wg-quick up wg0}}

For more information on {{c|wg-quick}} consult {{c|man 8 wg-quick}}.

==== netifrc ====

The {{Package|net-misc/netifrc}} scripts (typically used with OpenRC) can be used to quickly bring Wireguard interfaces. Presuming a correctly defined {{Path|/etc/wireguard/wg0.conf}} file has been created:

{{RootCmd
|ln -s /etc/init.d/wg-quick /etc/init.d/wg-quick.wg0
|rc-update add wg-quick.wg0 default
}}

To bring up the interface now:

{{RootCmd|/etc/init.d/wg-quick.wg0 start}}

===== Avoid using wg-quick =====

Using the <var>wg-quick</var> USE flag will add {{Package|virtual/resolvconf}} as dependency. For systems that want to keep the {{Path|resolv.conf}} file from being modified by external utilities this might be a deal breaker. {{Package|net-misc/netifrc}} now has native support for wireguard and {{c|wg-quick}} is no longer required. This assumes the wireguard interface configuration is defined in {{Path|/etc/wireguard/wg0.conf}}:

{{FileBox|filename=/etc/conf.d/net|lang=bash|1=
wireguard_wg0{{=}}"/etc/wireguard/wg0.conf"
}}

Remove "Address" and "DNS" from wg0.conf, because they won't be recognized by {{Package|net-misc/netifrc}}. Copy them and add to the config:

{{FileBox|filename=/etc/conf.d/net|lang=bash|1=
config_wg0{{=}}"1.2.3.4/32"
dns_servers_wg0{{=}}"5.6.7.8"
}}

Replace the values above with personal wireguard addresses. Either get them from a provider or configure them on the personal wireguard setup.

Create the symlink and bring the interface up when the system boots:

{{RootCmd
|ln -s /etc/init.d/net.lo /etc/init.d/net.wg0
|rc-update add net.wg0 default
}}

Bring the wireguard interface up:

{{RootCmd
|rc-service net.wg0 start
}}

Example /etc/conf.d/net file for netifrc with Wireguard instead of using wg-quick:

{{FileBox|filename=/etc/conf.d/net|lang=bash|1=
# Make sure to change all values for your setup! These are just an example.
#
# Make sure that net-dns/openresolv, virtual/resolvconf, their
# dependencies and other resolv.conf managers aren't installed,
# to keep the setup simple and secure! This might require you to
# add -wg-quick to net-vpn/wireguard-tools and rebuild the package.

# Bring up hardware network interface!
# Change enp5s0, to your interface, shown when running: ip addr
config_enp5s0{{=}}"dhcp"

# Setup a DNS server here if you're going to change to another DNS server
# when bringing up the Wireguard interface. Some providers give you an address.
# It's better to change the address for privacy reasons.
# Change enp5s0, to your interface, shown when running: ip addr
dns_servers_enp5s0{{=}}"1.2.3.4 123.12.21.1"

# Bring up Wireguard virtual network interface!
# The IP here is from your VPN provider or custom Wireguard setup.
config_wg0{{=}}"5.6.7.8/32"

# Connect to Wireguard endpoint using config!
# You need to create this config if it doesn't exist.
wireguard_wg0{{=}}"/etc/wireguard/wg0.conf"

# Prevent DHCP from setting a DNS server gotten from your router.
dhcp{{=}}"nodns"

postup() {
	# After the wg0 interface is up, we add routing and firewall rules,
	# which prevent packets from going through the normal routes, which are
	# for "plaintext" packets.
	# routing rules taken from: https://www.wireguard.com/netns/
	# firewall rules taken from: man wg-quick
	#
	# If the connection to the VPN goes down, the firewall rule makes sure
	# no other connections can be open, until you remove the interface
	# using: rc-service net.wg0 stop
	#
	# For the nftables firewall rule to work, make sure you set:
	# SAVE_ON_STOP="no"
	# in: /etc/conf.d/nftables
	if [ "${IFACE}" {{=}}{{=}} "wg0" ];
	then
		# set a firewall mark for all wireguard packets
		wg set wg0 fwmark 334455 {{!}}{{!}} exit 1
		
		# route all packets to the wg0 interface in table 2468
		ip route add default dev wg0 table 2468 {{!}}{{!}} exit 1
		
		# if packet doesn't have the wireguard firewall mark,
		# send it to table 2468
		ip rule add not fwmark 334455 table 2468 {{!}}{{!}} exit 1
		
		# if packet isn't going out the wg0 interface, doesn't have
		# the wireguard firewall mark and isn't broadcast or multicast
		# reject it (don't drop it like there's no connection)
		nft insert rule ip filter output oifname!{{=}}"wg0" mark!{{=}}334455 fib daddr type!{{=}}local counter reject {{!}}{{!}} exit 1
		
		# Make sure only DNS server is the one from your provider or
		# a custom one fitting your needs!
		# If there is one, otherwise you can remove this line.
		echo "nameserver 9.10.11.12" > /etc/resolv.conf {{!}}{{!}} exit 1
	fi
	return 0
}

predown() {
	# Prevent bringing down interface in case there's a NFS root.
	# taken from: https://github.com/gentoo/netifrc/blob/4bd8be5f43d07a9e92b73174c7fbef8b989aaa55/doc/net.example.Linux.in
	if is_net_fs /; then
		eerror "root filesystem is network mounted -- can't stop ${IFACE}"
		return 1
	fi

	# When bringing down the interface using rc-service, make sure that all
	# rules specific to isolating the wireguard connections are gone, so
	# that normal connections can work again.
	# Change the DNS values for your setup!
	if [ "${IFACE}" {{=}}{{=}} "wg0" ];
	then
		# Bringing back default nftables rules.
		rc-service nftables reload {{!}}{{!}} exit 1

		# Removing wireguard specific routing rules.
		ip route del default dev wg0 table 2468 {{!}}{{!}} exit 1
		ip rule del not fwmark 334455 table 2468 {{!}}{{!}} exit 1

		# Bringing back your own DNS settings, in case they were
		# changed in postup()
		echo "nameserver 1.2.3.4" > /etc/resolv.conf {{!}}{{!}} exit 1
		echo "nameserver 123.12.21.1" >> /etc/resolv.conf {{!}}{{!}} exit 1
	fi
	return 0
}
}}

==== NetworkManager ====

Wireguard is officially supported by NetworkManager as of version 1.16<ref>https://gitlab.freedesktop.org/NetworkManager/NetworkManager/blob/master/NEWS#L301-303</ref>. That stated, as of version 1.26.6, ''managing WireGuard is only possible through the {{c|nmcli}} command''. Review the [https://networkmanager.dev/docs/api/latest/settings-wireguard.html latest documentation upstream] for the extensive list of key-value properties.

{{Important|NetworkManager requires runtime dependencies (command-line interface tools) from the {{Package|net-vpn/wireguard-tools}} package in order to manage connection profiles. Be sure this package has been emerged before attempting to use {{c|nmcli}} command.}}

{{Important|In order for non-root users to edit network connections, each user must be [[NetworkManager#User_permission|added to the plugdev group]].}}

After creating a WireGuard configuration file (such as {{Path|wg0.conf}}), the file can be imported into NetworkManager as a connection profile:

{{Cmd|nmcli connection import type wireguard file /path/to/wg0.conf}}

After the configuration has been imported, the connection can be activated via:

{{Cmd|nmcli connection up wg0}}

See the [[NetworkManager]] article for more details on managing connection profiles.

== Removal ==

=== Unmerge ===

When removing Wireguard support be sure to each for all installed packages:

{{Emerge|params+=--search|wireguard}}

For example, to remove the userspace tools:

{{Unmerge|net-vpn/wireguard-tools}}

== Troubleshooting ==

=== Rebuilding modules on kernel upgrades for kernels less than 5.6 ===

When upgrading to a newer kernel that is less than version 5.6 (version 4.9.x LTS is a fitting example), it is important to re-emerge the 
Wireguard kernel modules. This is handled by default when using {{c|[[genkernel]]}}, but can be quickly performed using the following auto-generated Portage set:

{{Emerge|@module-rebuild}}

== See also ==

* {{See also|OpenVPN}}
* {{See also|vpnc}}

== External resources ==

* https://github.com/trailofbits/algo - A project with scripts to help setup a personal VPN server.
* http://lkml.iu.edu/hypermail/linux/kernel/1606.3/02833.html - The initial Request for Comments post to the Kernel Mailing List.
* https://www.latacora.com/blog/2018/05/16/there-will-be/ - A blog post complementing WireGuard.

== References ==

{{reflist}}

[[Category:Gentoo community software]]
[[Category:VPN]]