====== WireGuard VPN ======

===== Introduction =====

WireGuard can be configured and run via the web interface, or at the command line. Either lets you configure WireGuard settings and generate configuration files. This page describes how to configure Wireguard through the web interface.

Note that tabs or other interface components in your menus may be different colours, depending on which web interface theme is chosen in the Admin Access menu.

This HOWTO: [[wireguard_on_freshtomato|Set up WireGuard]] includes an introduction to WireGuard and some basic theory.

Unless using an external VPN provider, it's best to "nominate" a main router that will produce configuration files. Clients, such as other FreshTomato routers and other devices should import the configuration generated by the main router. Certain configuration changes may require you to delete and reimport the configuration on those client devices.

Note that WireGuard only supports UDP stream, not TCP.


===== Current development status =====

  * The web interface menu has been working since r2024.1. 
  * IPv4 is fully supported. IPv6 is not supported at this time.
  * The use of external VPN providers is supported starting with r2025.3.
  * Wireguard can import pre-generated configuration files from external \\ VPN providers starting with r2025.3. Files must be wg-quick compatible.
  * Policy-based Routing is supported since r2025.3
  * The kill switch feature is supported since r2025.3. 
  * Split-tunneling is supported in Policy-based Routing since r2025.3.

 \\

**Two serious bugs** in r2025.3 and earlier can cause kernel panics. See the [[https://wiki.freshtomato.org/doku.php/vpn-wireguard#wireguard_notes_and_troubleshooting|Notes and Troubleshooting]] section at the bottom for details.

 \\

These external VPN providers' scripts have been tested as working:

  * Coming soon: IVPN
  * Integrity VPN
  * NordVPN
  * PIA (Private Internet Access
  * ProtonVPN
  * SurfShark
  * Windscribe\\

 \\

If your VPN provider doesn't support generation of configuration files, this tutorial shows how to to //manually// configure your VPN settings:

[[https://www.linksysinfo.org/index.php?threads/wireguard-on-freshtomato.76295/page-23#post-348056|How to Connect to a VPN Provider's WireGuard Tunnel on FreshTomato]]


===== Status =====

 Icons here indicate the tunnel/service status, and also allow you to stop and start the tunnel/service.

 \\ \\

{{::vpn-wireguard-down-2025.3.png?76}}    indicates the Wireguard service isn't running and no VPN tunnel currently exists on this interface.  \\  \\

{{::vpn-wireguard-start_now-2025.3.png?76}}   clicking this starts the WireGuard service, and makes the interface negotiate a VPN tunnel to peers.

 \\ {{::vpn-wireguard-up-2025.3.png?76}}    indicates the selected WireGuard connection is running, and connected to the configured peers.

 \\

{{::vpn-wireguard-stop_now-2025.3.png?76}}   terminates the current WireGuard VPN tunnel and stops the service.


===== Wireguard Configuration =====

WireGuard uses virtual network adapters (or "network interfaces") on which to operate a VPN tunnel. The network interface WireGuard creates (such as "wg0") behaves like a standard network adapter. This interface routes your traffic through the encrypted tunnel between peers.

WireGuard allows you to create 3 separate network interfaces to allow for 3 separate VPN configurations (or "instances"). In Freshtomato, each network interface is represented by a tab, such as wg0, wg1, or wg2. The current tab selected appears in a different colour than the others. \\   \\   \\  {{::vpn-wireguard-wg0-2025.3.png?95}}  the first Wireguard interface/instance.

 \\

{{::vpn-wireguard-wg1-2025.3.png?95}}  the second Wireguard interface/instance.

 \\ \\ ** {{::vpn-wireguard-wg2-2025.3.png?95}} ** the third Wireguard interface/instance.

 \\  \\

Each interface/tunnel tab can contain its own unique configuration, encryption keys, and so on. Options for each interface are explained below.

\\   \\

 \\

{{::vpn-wireguard-config_tab-2025.3.png?95}}  here, enter the main configuration settings for the chosen interface.


===== Interface =====

Settings here are used to configure the router's WireGuard interface of this instance/tab, (such as "wg0").

 \\

**Enable on Start** - makes FreshTomato start WireGuard at boot, build the tunnel and connect to peers.

This is currently NOT recommended until some serious bugs are fixed. See the [[https://wiki.freshtomato.org/doku.php/vpn-wireguard#wireguard_notes_and_troubleshooting|Notes and Troubleshooting]] section for details.

 \\

**Poll Interval** - WireGuard's PersistentKeepalive setting.

This determines how often clients behind NAT send keepalive packets to maintain NAT mappings.

 \\

  * The recommended setting is 25 seconds. This causes WireGuard \\ to send a small packet to its peer every 25 seconds when no \\ other traffic occurs. This keeps the connection alive through \\ NAT or firewalls that might otherwise close idle UDP sessions. \\ \\ 
  * Default: 0. This disables the feature, so packets are sent only\\ as needed. This is fine for most users not behind restrictive NAT.

 \\

**Config file** - here, enter the path to a WireGuard configuration file.

The file must be wg-quick compatible. If a file is specified here, all other settings in the web interface will be ignored.\\

 \\

**Port** - the UDP the port on which the interface’s tunnel will be built with the remote endpoints.

This is similar to the “ListenPort” setting in a //wg-quick// configuration file. No entry makes WireGuard choose a different free UDP listening port at each start.

\\

**Private Key** - here, enter the private key for the VPN tunnel.

If you import a prebuilt configuration file from an external VPN provider, this should populate automatically.

 \\

**Public Key** - displays the tunnel's public key.

WireGuard automatically generates this using the Private Key. This field cannot be directly edited.

 \\

**VPN Interface IP** - the IP address to be assigned to the virtual network interface.

This is used only inside the tunnel, independent of physical interface IPs. It must be a unique address space reserved only for WireGuard, to prevent conflicts.

Valid entries are in CIDR notation. For example: "10.0.0.1/32". Addresses must be separated by commas or newline characters.

 \\ \\ **DNS Servers (out)** - the nameservers the client device will use for DNS lookups once the tunnel is active.

These can be:

 \\

  * Internal (private) to the VPN, such as a DNS resolver reachable only via the VPN.
  * Public, such as Google DNS (8.8.8.8) or Cloudflare (1.1.1.1).

 \\

This is usually needed in site-to-site topology VPNs. This is the same as the “DNS” setting in a wg-quick configuration file

\\

**FWMark** - used to mark outgoing encrypted packets with a firewall mark.

Use of this mark is helpful for configuring advanced routing decisions, such as policy-based routing. The system can differentiate/route WireGuard traffic based on the mark, often associating it with a specific routing table. This is the same as the “FwMark” setting in a wg-quick configuration file.

Packets marked with fwmark can be routed through a dedicated route table. This allows you to run complex routing scenarios, such as routing some traffic through the WireGuard tunnel (split-tunnel) or using multiple tunnels with different policies.

 \\

**MTU** - lets you set the Maximum Transmission Unit.

This is the largest packet size that can be sent over the WireGuard interface without fragmentation.

 \\

  * Setting the MTU correctly helps avoid packet fragmentation. \\ Fragmentation can cause slow speeds, connection drops, \\ and other inefficiencies.\\ \\ 
  * If MTU is too high, packets may exceed the size supported by \\ the underlying network. This could cause fragmentation or \\ packet drops.\\ \\ 
  * If set too low, it reduces efficiency by sending smaller packets \\ than necessary.\\ \\ 
  * Default for IPv4: typically around 1420 bytes (with 60 bytes \\ used for tunnel overhead).\\ \\ 
  * Default for IPv6: typically, the recommended MTU is 1280 bytes.

 \\

**Respond to DNS** - enables dnsmasq to resolve DNS queries that arrive on this interface.

 \\

**Routing Mode -** allows you to select the routing mode to use on the WireGuard interface.

This option appears only when one of the Internal VPN types is selected.\\  \\

  * Off - FreshTomato won't add any routing rules for this\\ WireGuard interface.\\ \\ 
  * Auto - choosing this means the WireGuard interface will be routed \\ using the default table (the same number as the interface port)\\ \\ 
  * Custom Table  -  this option will route the WireGuard interface \\ using a custom table number. If you choose this option, you must \\ include the table number in the additional field.

 \\

 \\ **Firewall** - lets you choose the appropriate firewall setting for your WireGuard setup. \\   \\

  * Automatic - when selected, FreshTomato will automatically generate \\ appropriate firewall settings for the WireGuard instance. This will cause \\ the Create NAT on tunnel and Inbound Firewall options to appear.\\ \\ 
    * Create NAT on tunnel - enables Network Address Translation \\ on the tunnel. When enabled, FreshTomato rewrites the source \\ addresses of packets going through the tunnel, so they appear \\ as if they originated from the router itself (using the router’s VPN \\ tunnel IP), rather than from their original LAN addresses. \\ This helps VPN clients behind the tunnel to access external \\ networks, such as the Internet.\\  \\ 
    * Inbound Firewall - adds firewall rules to let inbound Wireguard \\ traffic through the WAN interface. This opens the necessary \\ WireGuard port so clients can connect from outside networks. \\ Incoming WireGuard traffic is then accepted without requiring \\ additional manual firewall rule configuration. \\ \\
  * Custom - FreshTomato will not add WireGuard firewall rules. \\ You will need to add your own scripts in the Post-Up or Post-Down \\ fields in the Scripts tab. Alternatively, you could enter them in the

 \\   \\ **Type of VPN** - lets you set the type of VPN topology generated.

{{::vpn-wireguard-type_of_vpn-2025.3png.png?523}}\\   \\

  * Hub and Spoke - All peers can only communicate via the Hub. \\ \\ 
  * Full Mesh (defined Endpoint only) - FreshTomato will try to create  \\ a full mesh among peers with EndPoint defined. \\ \\ 
  * Full Mesh - FreshTomato will try to establish a full mesh \\ between all peers. \\ \\ 
  * External VPN Provider - FreshTomato will try to establish \\ a VPN connection with an external VPN provider.

 \\

Depending on the setting you choose, other fields will appear in which to configure more settings.

To learn about WireGuard topologies, see this webpage: [[https://www.procustodibus.com/blog/2020/10/wireguard-topologies/|Procustodibus: Primary WireGuard Topologies]]\\  \\

 \\

**Redirect Internet traffic** - lets you manage which traffic is directed through the tunnel and which isn't.

This option appears only when External VPN provider is selected in //VPN Type//. \\   \\

  * All - will route all outbound traffic from all connected LAN devices \\ through the VPN tunnel. Every network device will use the VPN \\ for outgoing internet connections. \\ \\ 
  * Routing Policy - this lets you create rules, specifying which devices \\ or destination addresses/subnets should have their Internet traffic \\ routed through the VPN or directly to the internet, without encryption. \\ This can include "split-tunneling". \\ \\ 
  * Routing Policy (Strict) - only explicitly-defined traffic will go through the\\ tunnel. All other traffic is excluded and can't use the tunnel.


===== Peer Parameters =====

Here, you can manually configure Peer settings. Some fields populate automatically if you import a configuration file instead of/in addition to manually entering settings.  \\  \\

**Router behind NAT** - sets whether/how often keepalive packets are sent from the router to defined peers.

(0=disable/no NAT, 10-99s range. A typical setting is 25). This helps maintain connections behind NAT devices.

 \\

**Endpoint - **sets how the router will be identified as an endpoint in configuration files generated in the Peers tab.

 \\

  * FQDN - the host name and domain name specified in the\\ Identification menu will be used to identify the router as endpoint.
  * WAN IP - the WAN IP address of the router will be \\ used to identify the router as endpoint. This should be used \\ when the IP address is fixed and won't change.
  * Custom Endpoint - a user-specified endpoint will be used. \\ If selected, you must enter the custom endpoint address \\ in the next field.

\\

**Allowed IPs** - here, enter the IP address ranges to be routed through the particular peer.

Outgoing packets bound for addresses in the "AllowedIPs" range will be sent through the tunnel to that peer. For example, if a peer has AllowedIPs = "172.16.0.0/24", then traffic to any IP in that subnet will be routed to that peer. Entries must be in CIDR format, separated by commas.

 \\

**DNS Servers for Peers** - the DNS Server addresses to use in the Interface section of generated configuration files.

Server addresses specified here will provide DNS name resolution for tunnel peers.

 \\

**Push LAN0 (br0) to Peers** - allows VPN peers to access LAN0

(As set in the Network menu).

 \\

**Push LAN1 (br1) to Peers** - allows VPN peers to access LAN1

(As set in the Network menu).

 \\ \\ **Push LAN2 (br2) to Peers** - allows VPN peers to access LAN2

(As set in the Network menu).

 \\

**Push LAN3 (br3) to Peers** - allows VPN peers to access LAN3

(As set in the Network menu).

 \\  \\ **Forward all peer traffic** - adding an Allowed IP of "0.0.0.0/0" will tunnel all traffic from the peer through the router's WireGuard interface.

 \\

**Peer behind NAT** - specifies this peer has an IP address on a private network, and connects to the VPN through NAT.

Enabling this causes WireGuard to send Keepalive packets from this peer to all other peers.

 \\   \\

{{::vpn-wireguard-peers-peers_parameters-add_to_peers-2025.3.png?80}} clicking this adds all completed settings in the section to the [Peers] section in the WireGuard Configuration file. \\   \\   \\ {{::vpn-wireguard-peers-peers_parameters-clean-2025.3.png?80}}** **clicking this will clear all fields in this section, but won't save those changes until you click Save.

 \\


===== Import Config from file =====

Available since r2025.3, this lets you quickly and easily import a pre-generated WireGuard configuration file. This file can come from an external VPN provider, or other source, such as another WireGuard endpoint. Files must be compatible with the wg-quick format (usually ending in "*.conf").

Typically, with an external VPN provider, you choose appropriate settings on their website for the configuration you want. The VPN provider then generates a corresponding configuration file to import. For most providers, this will be a wg-quick compatible file.

While FreshTomat's function requires a file to be wg-quick compatible format for import, it does not maintain that format, or even save a configuration file. Instead, after import, settings are divided up and stored in NVRAM as separate variables. To quickly view all the settings, use the "nvram show" command.

For example, typing:

''nvram show|grep wg0_''

 \\

will display all variables and their settings for the "wg0" interface. The only exception occurs when you copy a configuration file to a folder on the router and enter a path to that file in the //Config File// field. In that case, that file will be saved as a configuration file, in wg-quick format.

 \\

{{::vpn-wireguard-config_tab-import_config_from_file-choose_file-2025.3.png?95}} lets you browse for the configuration script to import (usually ending in ".conf").

{{::vpn-wireguard-config_tab-import_config_from_file-import-2025.3.png?95}} will import the configuration file you selected using the //Choose File// button.

 \\

These steps should successfully configure most, if not all necessary WireGuard settings. However, please ensure all relevant fields are populated to ensure WireGuard will work.

\\

{{::vpn-wireguard-peers_tab-2025.3.png?95|Peers}} in this tab, you enter settings for the peer devices.


===== Peers =====


This section allows you to enter and view settings for all peers of this WireGuard interface/instance.

==== Peers (Table) ====

Each row in this table represents a network peer. Peers are NOT added here. They're added in the //Peer's Parameters// section. However, you can click a pre-existing table row to edit its settings in //Peer's Parameters//.

 \\ {{::vpn-wireguard-peers_tab-peers_table-2025.3.png?874}}

 \\

**QR** - shows a QR code for this peer.

The QR code contains the entire configuration for this WireGuard peer. For it to work properly, you must click the QR code button to display it at full size. You can then take a photo of it to allow WireGuard on your smartphone or other device to quickly grab and import this interface's Peer settings. This way, you can quickly and securely transfer Peer configurations without having to manually enter settings. This makes setup faster, easier and more accurate.\\

 \\

**Cfg** - clicking this will generate and download this peer's configuration file.

This button will only appear when a //Mesh// or //Hub and Spoke// option is chosen in VPN Type. If a download window doesn't appear, check that your browser isn't blocking file downloads and popup windows from the router.

 \\

**Alias** - here, you can enter a custom name for this peer.

For example, you could enter "Head Office" to indicate the Peer's location. \\

 \\ **Endpoint** - the IP address here will act as an endpoint for this peer's WireGuard interface.

The endpoint is the "real" (unencrypted) address where this peer can be reached over the Internet/WAN. Enter an IP address or a fully qualified domain name followed by a colon and the UDP port. For example: "116.0.110.4:51820". This tells the local WireGuard instance where to send encrypted packets for this peer inside the tunnel.

Leaving this empty sets the the peer as "dynamic". This causes the endpoint address to be learned automatically when the peer initiates a connection. You only need to specify a value on one side of the connection. The other side will learn it dynamically when incoming traffic arrives.

 \\

**Public Key** - the public key for this peer's WireGuard interface/instance.

If you click on a completed table row, this field will display any existing key for that peer. If entering data for a new Peer in the Peer's Parameters section, you must complete either the Public Key or Private Key fields. Otherwise nothing will appear in the corresponding table field.

\\ \\ **IP** - the IP address of this peer's WireGuard interface.

This displays the IP and Netmask that willl be used for this peer, in CIDR format.

\\


===== Peer's Parameters =====

This area allows you to manually configure Peer settings. Note that some fields here may populate automatically if you import a configuration file instead of/in addition to manually entering settings. This section is available only if one of the Internal VPN types is selected. \\  \\   \\ **Alias** - here, enter a name or description of your choice for this peer.

This can help you quickly recognize the purpose of each peer or the device owner or device on which it's running. This makes it easier to document and audit VPN configurations, track device ownership.

 \\

**Endpoint** -  the unencrypted IP address/hostname and UDP port where the peer can be reached.

This tells WireGuard where to send encrypted VPN traffic going to that peer. Valid entries include an IP address or DNS name, followed by a port number. For example: 206.229.204.23:1022. The Peer with the endpoint defined will initiate communication.

 \\

**Private Key** -   the secret cryptographic key unique to this peer.

This key is used to prove the peer’s identity and to decrypt incoming encrypted traffic. It grants access to the encrypted VPN tunnel.

 \\

**Public Key** - the public key shared with other peers to allow encrypted traffic to be sent to this peer.

Every WireGuard peer has a unique public-private key pair. This public key identifies the remote peer you want to communicate with, so WireGuard knows which key to use to encrypt packets sent to that peer.

 \\

**Preshared Key** -  an optional secret to add an extra layer of symmetric-key cryptography.

This is a secret key that WireGuard mixes into the key derivation process for its tunnel encryption. By using a preshared key, the noise protocol's encryption keys are strengthened, offering increased security, particularly as a hedge against potential future threats such as quantum computers or key theft. Both ends of a WireGuard connection using a preshared key must have the exact same key.

\\

**VPN Interface IP** -  a virtual address within the VPN subnet assigned to the peer.

This IP address is assigned to the WireGuard interface of the peer and uniquely identifies that peer inside the VPN tunnel.

\\

**Allowed IPs** - here, specify the IP address ranges to be routed through the particular WireGuard peer.

Outgoing packets bound for addresses in the "AllowedIPs" range will be sent through the tunnel to that peer. For example, if a peer has AllowedIPs = 172.16.0.0/24", then traffic to any IP in that subnet will be routed to that peer.

 \\

**Source IP Filtering for Incoming Traffic** - acts as an access control filter for incoming traffic from this peer.

WireGuard will only accept packets from the peer if its source IP address matches one of the specified "AllowedIPs". Incoming packets from that peer with source addresses outside the allowed IP ranges will be discarded. This enhances security.

 \\

**Peer behind NAT** - specifies this peer has an IP address on a private network, and connects to the VPN through NAT.

Enabling this causes WireGuard to send Keepalive packets from this peer to all other peers.

 \\   \\

{{::vpn-wireguard-peers-peers_parameters-add_to_peers-2025.3.png?80}} clicking this adds all completed settings in the section to the [Peers] section in the WireGuard Configuration file. \\   \\   \\ {{::vpn-wireguard-peers-peers_parameters-clean-2025.3.png?80}}** **clicking this will clear all fields in this section, but won't save those changes until you click Save.


===== Status =====

The Status tab displays data about the status of this WireGuard interface and hopefully, when a tunnel is up, its Peer's interface. Such information can be useful for troubleshooting or administration.

If a link is up, the handshake done and the tunnel established, you should see the peer's interface ID, and the the time of the latest handshake process. You should also see real-time traffic data such as bytes transmitted (tx) and bytes received (rx). These details confirm the tunnel is established and data is flowing through it.

For example, for this WireGuard instance:

 \\ \\ {{::vpn-wireguard-status-2025.3.png?473}}

\\

The first block of text includes this router's:

  - WireGuard Interface name
  - Interface's alias (if set)
  - Public key
  - UDP listening port

 \\

The second block of text displays the Peer's: \\

  - Public Key
  - Endpoint IP address
  - Allowed IPs
  - Latest Handshake performed
  - Number of bytes sent and received by this peer


===== WireGuard Notes and Troubleshooting =====

==== Known Issues ====

 \\

  - A bug in FreshTomato's CTF support for Wireguard can result in \\ a kernel panic and router reboot right after bringing up the wg0 \\ interface. This is believed to have been fixed. The fix should be \\ available in r2025.4 or in an image built from the current git. \\ For earlier releases, there are some reports that disabling CTF \\ functions as as a workaround.
  - Another serious bug exists in which a kernel panic and reboot \\ may occur if the WAN interface is disconnected. This may occur \\ even when the disconnect is expected, such as when clicking \\ //Release Connection// in the Overview menu.
  - Some users have reported speed issues when enabling CTF \\ with Wireguard running, while others have experienced no issues \\ or even greatly increased throughput.

 \\


==== General Troubleshooting ====

 \\

Please remember these troubleshooting tips when trying to configure your VPN:

  * **wg show** (via the command line) output will help you \\ understand the relationship between peers.
  * **route** (via the command line) can help you to verify \\ routing decisions when the VPN is connected.
  * **traceroute** is a must when verifying end-to-end connectivity. \\ A good approach is to test the following in order:
    * Local LAN IP
    * Local VPN IP
    * Remote VPN IP
    * Remote LAN IP

 \\  The point of failure found will provide critical insight into the type of issue you are facing.

 \\

 \\