wgu

README

wgu

wgu (WireGuard Userspace, pronounced "woo-goo" or "w-g-u") is a fork of Jonathan Giannuzzi's wgfwd. wgu creates WireGuard tunnels without superuser privileges. Connections to network services are managed using forwarders. Each forwarder tells wgu where to listen for incoming connections and where to forward connections to.

Think of wgu like SSH port forwarding, but with WireGuard instead of SSH.

If you would like a graphical version of wgu, check out Seung Kang's wgui.

Features

wgu expands on wgfwd's functionality with the following features:

• Automatic address planning mode: Optionally address peers' WireGuard interfaces using their public keys as IPv6 addresses. This mode makes it easy to quickly build simple WireGuard networks
• Specify which side of the tunnel a network listener should be created on
• Network listener and dialer type customization allows mixing of network protocols (for example: forwarding Unix sockets over TCP / UDP)
• Support for WireGuard configuration syntax via a configuration file
• Support for commonly-used wg helper commands like genkey and pubkey
• New genconf command auto-generates a configuration file to make getting started easier
• Support for resolving peers' external addresses using DNS hostnames
• Store the private key in a file outside of the configuration file
• Expand the WireGuard interface's address and peers' addresses using variable strings
• Specify multiple addresses for the virtual WireGuard network interface using more than one Address parameters
• Tap and packet capture functionality (disabled by default at compile-time)

Installation

First install Go. Once Go is installed, the application can be securely compiled from source and saved to ~/go/bin by executing:

# Note: The resulting executable will be located in ~/go/bin:
go install gitlab.com/stephen-fox/wgu@latest

Examples

$ # Generate a config file by executing:
$ wgu genconf
z9yJgu9cvwbygPzuUtzcmkuB2K2nxA6viKj1kUDj4Ug=
$ # Create the WireGuard tunnels by executing:
$ wgu up

For detailed examples, refer to the examples documentation or execute wgu help | less.

Configuration

Please refer to the configuration documentation

Commands

Please refer to the commands documentation

Troubleshooting

Startup failure in FreeBSD jail with host networking

If you are trying to run wgu in a FreeBSD jail that utilizes the host's networking stack and you are encountering the following error:

failed to set listen_port: listen udp6 :X: socket: protocol not supported

... it is likely you need to enable IPv6 in the jail configuration file like so:

 example {
   path = "/zroot/jails/${name}";
   ip4 = "inherit";
+  ip6 = "inherit";
   mount.devfs;
   exec.start = "/bin/sh /etc/rc";
   exec.stop = "/bin/sh /etc/rc.shutdown";
 }

Packet transit problems and packet captures

wgu provides functionality for capturing unencrypted traffic transiting the WireGuard tunnel via the Tap configuration parameter and the wgupcap tool. Tap functionality is disabled by default for security. Tap functionality can only be enabled by doing the following:

• Enabling the feature at compile-time
• Configuring the feature in the configuration file

For more information on this topic, please refer to the configuration documentation.

Special thanks

wgu would not have been possible without Jonathan Giannuzzi's original wgfwd project - thank you, Jonathan.

Thank you to @SeungKang for helping me implement features and fix bugs, plus spending tons of time testing :)

Documentation

Overview

wgu (WireGuard Userspace, pronounced "woo-goo" or "w-g-u") is a fork of Jonathan Giannuzzi's wgfwd. wgu creates WireGuard tunnels without superuser privileges. Connections to network services are managed using forwarders. Each forwarder tells wgu where to listen for incoming connections and where to forward connections to.

Think of wgu like SSH port forwarding, but with WireGuard instead of SSH.

If you would like a graphical version of wgu, check out Seung Kang's wgui.