Site Tools


vpn-wireguard

WireGuard VPN

Introduction

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

To manually configure WireGuard, and for some basic theory, see this HOWTO: Set up WireGuard . That page is more suitable for when you want to configure VPNs with a hub-and-spoke or mesh topology. It is less helpful when configuring an external VPN provider.

Unless using an external VPN provider, it's best to “nominate” a main router that will produce configurations. Clients, such as other FreshTomato routers and other devices must 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 WireGuard 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 WireGuard 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


Alternatively, many have successfully used the following tutorial to manually configure settings for an external VPN Provider:

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.



indicates the Wireguard service isn't running and no VPN tunnel currently exists on this interface.

clicking this starts the WireGuard service, and makes the interface negotiate a VPN tunnel to peers.


indicates the selected WireGuard connection is running, and connected to the configured peers.


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. WireGuard creates a virtual network interface (such as “wg0”) on your device that behaves like a standard network adapter. This virtual adapter routes your traffic through the encrypted tunnel between peers.

Wireguard allows you to create 3 separate virtual network adapters to allow for 3 separate VPN configurations (or “instances” in WireGuard terminology). In Freshtomato, each virtual adapter is represented by a tab, such as wg0, wg1, or wg2. The current tab selected appears in black.


the first Wireguard interface/instance.


the second Wireguard interface/instance.



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.




here, enter the main configuration settings for the chosen interface.

Interface


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 WireGuard 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 causes WireGuard to 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’s IPs. It must be a unique address space reserved only for WireGuard, to prevent conflicts with networks/peers.

It must be written using 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 hub-and-spoke or mesh 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.



  • 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: 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.

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. These 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 script to import.


lets you browse for the configuration script you wish to use (usually ending in “.conf”).

will import the configuration file you selected using the Choose File button.


These steps should successfully configure most, if not all necessary WireGuard settings. Nevertheless, it's wise to check that all relevant fields are populated to make sure WireGuard will work.


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.



QR - shows a QR code for this peer.

The QR code contains the entire configuration for the WireGuard peer. Taking a photo of it allows WireGuard on your smartphone or other device to quickly grab and import this interface's Peer settings.

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 once a tunnel is up.

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.

Alias


Endpoint -


Private Key -


Public Key -


Preshared Key -


VPN Interface IP -


Allowed IPs -


Peer behind NAT -



Clicking Save to Peers will add all completed settings in this section to the [Peers] section of the WireGuard Configuration file


Clicking Clean will clear the content of all fields in this section, but will not save those changes until you click Save.

Status

The Status tab contains data about the status of this WireGuard interface and its Peer's interface.




Data here include this interface's:

  1. Interface name
  2. Interface's alias (if any)
  3. Public key
  4. UDP listening port


It also displays the Peer's:

  1. Public Key
  2. Endpoint IP address
  3. Allowed IPs
  4. Latest Handshake performed
  5. Number of bytes sent and received by this peer

WireGuard Notes and Troubleshooting

Known Issues


  1. 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.
  2. 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.
  3. 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.



vpn-wireguard.txt · Last modified: by hogwild