Wireguard VPN~

WireGuard® is an extremely simple yet fast and modern VPN that utilizes state-of-the-art cryptography. This component uses a custom implementation not developed by original authors and currently available for ESP32, ESP8266 and BK72xx microcontrollers only. The Tasmota port of Wireguard is based on the works done on ESPHome and https://github.com/droscy/esp_wireguard.

To successfully use this component you must have WireGuard® also on your remote host (already installed and ready to accept connections). If you don't have it please read the section Remote peer setup.

Configuring Wireguard~

A VPN tunnel can be created to a single remote peer adding, by adding the client configuration in the file wireguard.conf. You should be able to simply copy/paste from the standard configuration file generated by the Wireguard server.

Parameters in wireguard.conf:

[Interface]
PrivateKey = <priv_key>
Address = 192.168.254.6/24
DNS = 9.9.9.9, 149.112.112.112

[Peer]
PublicKey = <pub_key>
PresharedKey = <psk>
Endpoint = <endpoint>:<port>
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 25

[Tasmota]
Netmask = 0.0.0.0
AutoConnect = 0

Parameters:

• [Interface]/PrivateKey (required, string): The private key of the device generated by the server.
• [Interface]/Address (required, IP/mask): The VPN address of the device. The mask length (/24 or /32) sets the default AllowedIPs, and can be left to its default value.
• [Interface]/DNS (optional, list of IP addresses): The DNS servers to be used when the VPN is active. This is especially useful when the Tasmota device uses a DNS relay on the LAN that would not be reachable by the VPN server; in such case set public DNS addresses. Note: this is currently ignored
• [Peer]/PublicKey (required, string): The private key of the device generated by the server.
• [Peer]/PresharedKey (required, string): The chosen pre-shared key between local device and remote peer, generated by the server.
• [Peer]/Endpoint (required, IP or domain:port): The hostname or IP of the remote peer, with its port number.
• [Peer]/AllowedIPs (optional, list of IPv4 ranges): A list of networks in CIDR notation (IP/mask) to be allowed through the tunnel.The range [Interface]/Address is always added by default to this list.
• [Peer]/PersistentKeepalive (optional, int): Number of seconds between keep-alives sent to the server (by default 0 = none). The recommended value is 25 seconds to help maintain connections through NATs and firewalls by sending periodic packets.
• [Tasmota]/Netmask (optional, IPv4 mask, default 0.0.0.0): Sets the internal IP mask for the LwIP network interface. Hence all IPs within the mask will be routed to the VPN instead of the default network (Wifi/Eth). If omitted, the default value is 0.0.0.0 which means that all packets are sent to Wireguard and none to the local network. Even if all packets are sent to Wireguard, the acutal packet sent to the VPN server are those listed in AllowedIPs, all other packets are discarded. See below for routing.
• [Tasmota]/AutoConnect (optional, int or bool, default 0): If set to 1 or true, Tasmota creates a Wireguard tunnel as soon as a network connection is up, and auto-reconnects if networks goes off and on again. Calling WGStop command disables AutoConnect until next boot.

Commands~

The following commands are added:

• WGConnect: establish connection, shows WG : Wireguard peer UP when peer is up (i.e. handshake was succesful)
• WGStop: stop Wireguard connection, shows WG : Wireguard peer DOWN when peer is down. If AutoConnect was true, WGStop sets it to false to avoid auto-reconnect (note: configuration is not changed, so AutoConnect will be enabled again after a reboot).

Static routing and outgoing connections~

(This section is heavily copied from ESPHome)

Currently there is no way on ESP devices to configure static routes for network interfaces. The routes are implicitly added by the configured netmask and only packets with destination inside the same network defined by [Interface]/Address and [Tasmota]/Netmask will be routed to the tunnel.

After packets are routed to the tunnel, [Peer]/AllowedIPs list is used only to allow (or drop) packets that pass through the VPN tunnel, not to define static routes for remote hosts.

This means that you have to tweak the [Tasmota]/Netmask parameter to "cover" all the networks in the allowed IPs list in order to successfully establish outgoing connections to remote hosts. Incoming connections are not affected by netmask on ESP32 (currently ESP8266 drops incoming packes as well).

Wireguard Routing Table~

Limitations~

Currently Wireguard for Tasmota has the following limitations:

• Wireguard VPN is currenlty only tested over Wifi, it has not been tested yet over Ethernet nor dual Eth/Wifi connections.
• the DNS field is currently ignored; which means that DNS may fail if it uses a DNS relay on your local network that is not reachable by your VPN server
• you can connect only to one peer at a time. Alghough the underlying library could connect to multiple peers, LwIP used in Tasmota does not support static routes which would made routing to multiple peers not practical
• On ESP8266, when a VPN connection is enabled, the Web UI is not reachable anymore. This problem does not occur on ESP32.