Difference between revisions of "WireGuard"

From Gentoo Wiki
Jump to:navigation Jump to:search
(→‎Kernel 5.6 and higher: rm 2nd person per guidelines, source spacing)
(→‎Kernel module loading: Add reference to CONFIGURATION FILE FORMAT section of the man page for help writing a configuration file.)
Line 102: Line 102:
  
 
Loaded modules can be reviewed with {{c|lsmod}}.
 
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 ==
 
== Usage ==

Revision as of 21:35, 2 August 2022

WireGuard is 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 Jason A. Donenfeld (zx2c4) , a Gentoo developer.

Official and potentially more up-to-date installation instructions can be 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:

  • CONFIG_NET - For basic networking support.
  • CONFIG_INET - For basic IP support.
  • CONFIG_NET_UDP_TUNNEL - For sending and receiving UDP packets.
  • CONFIG_NF_CONNTRACK - For determining the source address when constructing ICMP packets.
  • CONFIG_NETFILTER_XT_MATCH_HASHLIMIT - For ratelimiting when under DoS attacks.
  • CONFIG_IP6_NF_IPTABLES - Only if using CONFIG_IPV6 for ratelimiting when under DoS attacks.
  • CONFIG_CRYPTO_BLKCIPHER - For doing scatter-gather I/O.
  • CONFIG_PADATA - For parallel crypto (only available on multi-core machines).[1]
KERNEL Enable kernel support for WireGuard[2]
[*] 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:

KERNEL Enable CONFIG_WIREGUARD
Device Drivers  --->
    [*] Network device support  --->
        [*] Network core driver support
        <*>   WireGuard secure network tunnel

Also enable (without this connection will be impossible):

KERNEL Enable CONFIG_CRYPTO_ECDSA
_*_ Cryptographic API  --->
    <M> ECDSA (NIST P192, P256 etc.) algorithm

Working kernel config.

USE flags

USE flags for net-vpn/wireguard-tools Required tools for WireGuard, such as wg(8) and wg-quick(8)

selinux !!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur
wg-quick Install the wg-quick(8) helper tool. Most users want to use this.
Data provided by the Gentoo Package Database · Last update: 2022-05-05 09:51 More information about USE flags

Emerge

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

root #emerge --ask net-vpn/wireguard-tools

Less than 5.6

For Linux kernels less than 5.6 also install the modules:

root #emerge --ask 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 /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 /etc/modules-load.d/ directory in order to instruct the module loading service to get the module loaded on boot:

FILE /etc/modules-load.d/wireguard.conf
wireguard

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

root #modprobe wireguard

Loaded modules can be reviewed with lsmod.

Files

wg.conf

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

user $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:

FILE wg0.confWireguard configuration file example
[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 wg(8):

user $$(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 wg-quick utility, which will create tunnels using configuration files in the /etc/wireguard file:

root #wg-quick up wg0

For more information on wg-quick consult man 8 wg-quick.

netifrc

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

root #ln -s /etc/init.d/wg-quick /etc/init.d/wg-quick.wg0
root #rc-update add wg-quick.wg0 default

To bring up the interface now:

root #/etc/init.d/wg-quick.wg0 start
Avoid using wg-quick

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

FILE /etc/conf.d/net
config_wg0="192.168.255.1/24"
wireguard_wg0="/etc/wg0.conf"

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

root #ln -s /etc/init.d/net.lo /etc/init.d/net.wg0
root #rc-update add net.wg0 default

Bring the wireguard interface up:

root #rc-service net.wg0 start

NetworkManager

Wireguard is officially supported by NetworkManager as of version 1.16[3]. That stated, as of version 1.26.6, managing WireGuard is only possible through the nmcli command. Review the latest documentation upstream for the extensive list of key-value properties.

Important
NetworkManager requires runtime dependencies (command-line interface tools) from the net-vpn/wireguard-tools package in order to manage connection profiles. Be sure this package has been emerged before attempting to use nmcli command.
Important
In order for non-root users to edit network connections, each user must be added to the plugdev group.

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

user $nmcli connection import type wireguard file /path/to/wg0.conf

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

user $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:

root #emerge --ask --search wireguard

For example, to remove the userspace tools:

root #emerge --ask --depclean --verbose 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 genkernel, but can be quickly performed using the following auto-generated Portage set:

root #emerge --ask @module-rebuild

See also

  • OpenVPN — software that enables the creation of secure point-to-point or site-to-site connections.

External resources

References

  1. ↑ https://www.wireguard.io/compilation/#kernel-requirements
  2. ↑ https://www.wireguard.io/compilation/#kernel-requirements
  3. ↑ https://gitlab.freedesktop.org/NetworkManager/NetworkManager/blob/master/NEWS#L301-303
Retrieved from "https://wiki.gentoo.org/index.php?title=WireGuard&oldid=1080553"