WireGuard Tunnel

This document provides an introduction to the WireGuard tunnel and UI.

Introduction to WireGuard Tunnels

WireGuard is a modern, fast, and secure VPN tunneling protocol designed to be more efficient and user-friendly than traditional solutions like IPsec and OpenVPN. In WireGuard, a peer is an endpoint in the VPN tunnel and can function as either a client or a server. While WireGuard treats all peers equally in principle, practical considerations such as IPv4 limitations, NAT traversal, and firewall restrictions often result in a client-server deployment model.

WireGuard is distinguished by its high performance and leverages advanced cryptography to provide secure, efficient network tunnels. It is lightweight, simple to configure, and highly performant. Each WireGuard tunnel is composed of a network interface and multiple peers. Every peer in the tunnel possesses a unique public-private key pair, an endpoint address, and routing rules specified by its allowed IPs. WireGuard uses UDP as its transport protocol and supports a keep-alive mechanism to maintain connectivity even on restrictive networks. Additionally, it provides APIs for logging and troubleshooting tunnel issues.

From a user perspective, a WireGuard tunnel peer can be configured in either "Road Warrior" or "Site-to-Site" mode. Both modes utilize the same key-pair authentication process for secure connections.

---

Road Warrior Mode

Road Warrior mode is designed for connecting portable devices—such as laptops and mobile devices—to a remote tunnel endpoint, typically an edge controller like a CPE or vCPE. In layman’s terms, this is similar to a client-server model, with the edge controller handling one-to-many connections. In Road Warrior mode, an additional feature allows the server or edge controller to generate peer keys for clients and create client configuration manifest files. These manifest files can then be imported into the client device, enabling seamless connection to the server or remote endpoint.

If the "Generate Key Pair" option is selected for a peer in Road Warrior mode, additional parameters are required to create the client configuration manifest file. These parameters are specified in the API input.

---

Site-to-Site Mode

Site-to-Site mode is intended for connecting two static edge controllers, such as CPEs or vCPEs. In this mode, the tunnel interfaces and peer configurations must be manually created by providing appropriate endpoint configuration information. This setup is analogous to a point-to-point connection between two devices.

---

Summary Table

Mode	Description	Typical Use Case
Road Warrior	Portable devices connect to an edge controller	Laptops, mobile devices
Site-to-Site	Two static edge controllers connect directly	CPE-to-CPE, vCPE-to-vCPE

UI Overview

This sections explains functionalities provided in UI for managing wireguard tunnels and its peers in the zWAN-CPE.

The main functionalities in UI are as follows

Creation of Wireguard Tunnel

Navigate to the Tunnels page and click on the ‘WIREGUARD’ tab. Click on the "CREATE TUNNEL".

Provide the needed the info such as description and port number. Also either provide an existing key pair info if any or generate a new key pair to create a new tunnel.

List Wireguard Tunnels

Once a wireguard tunnel is created, the page lists the created tunnels in the page.
Each Wireguard tunnel will be assigned a name from the firmware with names such was ‘WG0000’, ‘WG0001’ etc.

Edit Wireguard Tunnel

To update any existing options of the tunnel use the edit (pen icon) button under the Actions. Edit can be used to update description/port/create a new key pair for the tunnel or enable or disable the tunnel. If new key pair is generated the new public key should be updated accordingly in the peers connected to tunnel.

Delete Wireguard Tunnel

The tunnel can be deleted using the delete (trash icon).

Add IP to the tunnel

An IP should be assigned to the tunnel. Click on the Add IP (+ icon) in the list page. Based on the number of clients, the subnet mask of the ip should be assigned. In this example /24 netmask is assigned.

Update the MTU of the tunnel

The default MTU assigned to the tunnel is 1420. If the MTU needs to be changed, click on the edit (pen icon) near the MTU to change it to the desired value.

Enable/Disable the Tunnel

The tunnel can be enabled or disabled using the switch icon under Status in the list view. This can be used for troubleshooting any issues with the tunnel.

Enable/Disable logging for the Tunnel

Click on the switch icon next to Wireguard Logging to Enable/Disable logging for the tunnel. This option is also useful for troubleshooting any issues with respect to tunnel connectivity. Make sure to disable the logging once the troubleshooting process is over.

Configuring Peers

Click on the redirect icon under Peer section in list view to configure peers for the corresponding tunnel. This will redirect to a new page which list peers configured to connect to this tunnel device.

Adding a Road Warrior Peer to a tunnel

Click on "ADD PEER" button to add a new peer config for this tunnel. A dialog box will pop-up which needs to be updated accordingly for adding a peer to the tunnel.

As mentioned above there are two types. Currently only Road warrior mode is supported. In Road warrior mode user can enter an existing peer’s info or create a completly new peer config such as generating the client’s key pair which then can be imported as a manifest file in the client device. Add the peer info which needs to be updated in the server side in the top section.

Adding a Road Warrior Peer by creating a manifest file for the client

The top section of this dialog box covers the details of the peer (client mobile device) which should be updated in the CPEs wireguard config file (Server).

When adding a new peer with manifest file support, select the Generate New Key Pair option. Fill in the required fields under the Client Interface info and Client Peer info which is needed to update the client’s (mobile device) config file.

Under the Client Peer Info, to route all the traffic via the tunnel it is recommended to specify the allowed subnets as 0.0.0.0/1 and 128.0.0.0/1 instead 0.0.0.0/0 to avoid routing loops.

Update Peer info

The peer info can be updated using the edit icon under the Actions column in the list page.

List Peers

Once a peer is added, it will be listed in the list page.

Delete peer

The peer config can be deleted using the delete icon under the Action column in list peer page.

Download manifest file for a client from list peer page

The manifest can be downloaded using the download icon under the Actions column in the list peer page

Enable/Disable the Peer

The peer can be disbled/enabled using the enable/disable switch under the Status column in the list page or from the edit peer dialog.

Connect the client device using the manifest file

Once the peer(client) info is added in server and manifest file is generated, its time to connect the client(mobile device) to the server (Edge controller/CPE).

Download the manifest file to the local device (laptop) or mobile device. The manifest file can be downloaded from zWAN CPE UI from the list peer page as mentioned in one of the above sections Download manifest file for a client from list peer page

Manifest File Naming Behavior

Manifest File Naming Behavior

When saving the manifest file locally or downloading it via the user interface, if a file with the same name already exists in the destination directory, the new file may be saved with additional spaces or special characters such as parentheses () in its filename.

Important: The filename is used as the name of the WireGuard tunnel on the client device.

The manifest filename is derived from the Peer Name specified in the peer configuration. To ensure consistency and avoid potential issues, filenames must comply with the following constraints:

• Be 1 to 15 characters in length
• Contain only the following characters:
  • Letters: A–Z, a–z
  • Numbers: 0–9
  • Symbols: _, =, +, ., –

Filenames that do not meet these requirements may lead to unexpected behavior or compatibility issues.

Note: If the filename does not conform to the above rules, please rename the file manually to match the required WireGuard tunnel naming constraints.

Launch the wireguard client app on the laptop.

Click on the import file option and tunnel will be added.

Activate the tunnel device.

Once the tunnel is activated, the transfer and last handshake sections will be updated with send/received bytes and time respectively. If received bytes is incrementing, it means tunnel is connected to the server and is able to transfer data.

An tunnel activated event will be notified in the device.

You can also use ping command to test the connectivity to the server.

Limitations

The wireguard road warrior support is currently supported only from 1.3-06 firmware versions. Its not supported in 1.4 firmware version.

User authentication for roadwarrior installations is not supported.

Site to Site mode is not supported for this current release. This needs NetBalancer support for wireguard tunnels.

Future enhancements

Site to Site wil be supported in the upcoming releases.

References

https://www.youtube.com/watch?v=b58PpuIsQ3A

https://markliversedge.blogspot.com/2023/09/wireguard-setup-for-dummies.html

https://www.comparitech.com/blog/vpn-privacy/road-warrior-vpn-wireguard-pfsense/

https://docs.opnsense.org/manual/how-tos/wireguard-client.html

https://github.com/Fruxlabs/wireguard-roadwarrior/blob/master/wireguard-install.sh

Summary

This document provides a structured explanation of WireGuard tunnels and their associated operations. The wireguard-api-01.md defines essential queries and mutations for managing tunnels and peers, enabling teams to build efficient UI and testing workflows.