WireGuard Component

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.

Please note that “WireGuard” and the “WireGuard” logo are registered trademarks of Jason A. Donenfeld. See “WireGuard” Trademark Usage Policy for additional information.

⚠️ Warning

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.

⚠️ Warning

This component requires the system clock to be synchronized.

See Time Component to setup a time source and do not use homeassistant time-platform if Home Assistant is on the remote peer because the time synchronization is a prerequisite to establish the VPN link.

The SNTP Time Source is a valid time-platform choice.

A VPN tunnel can be created to a single remote peer adding the following to your configuration:

# Example configuration entry
wireguard:
  address: x.y.z.w
  private_key: AaBbCcDd...=
  peer_endpoint: wg.server.example
  peer_public_key: EeFfGgHh...=

  # Optional netmask (this is the default, no outgoing traffic
  # will pass through the tunnel if omitted)
  netmask: 255.255.255.255

  # Optional endpoint port (WireGuard default if omitted)
  peer_port: 51820

  # Optional pre-shared key (omit if not in use)
  peer_preshared_key: XxYyZzWw...=

  # Optional list of ip/mask (any host is allowed if omitted)
  peer_allowed_ips:
    - x.y.z.0/24
    - l.m.n.o/32  # the /32 can be omitted for single host
    - [...]

  # Optional keepalive (disabled by default)
  peer_persistent_keepalive: 25s

It is recommended to use secrets at least for private and pre-shared keys:

wireguard:
  private_key: !secret wg_privkey
  peer_preshared_key: !secret wg_shrdkey

Configuration variables

• address (Required, IPv4 address): The local VPN address of the device.

  If you intend to upload firmwares through the VPN link you probably need to copy this value to the use_address parameter of the WiFi Component.

• netmask (Optional, IPv4 address): The netmask for the configured address. Default to 255.255.255.255.

  See section Static routes and outgoing connections if outgoing connections are expected to transit through the VPN link (e.g. with MQTT Client Component to a remote MQTT broker).

• private_key (Required, string): The private key of the device.

• peer_endpoint (Required, string): The hostname of the remote peer.

• peer_port (Optional, UDP port): The port where remote peer is listening on. The WireGuard® default is 51820.

• peer_public_key (Required, string): The public key of the remote peer.

• peer_preshared_key (Optional, string): The chosen pre-shared key between local device and remote peer.

• peer_persistent_keepalive (Optional, Time): The amount of time after which a keepalive packet is sent through the tunnel. By default this feature is disabled (0s ).

  If there are NATs or firewalls between the device and the remote peer set this value to something like 25s.

• peer_allowed_ips (Optional, list of IPv4 networks): A list of networks in CIDR notation (IP/mask) to be allowed through the tunnel. Any host (0.0.0.0/0 ) will be allowed if this parameter is omitted.

  The device own address/32 is always added by default to this list.

  See section Static routes and outgoing connections if outgoing connections are expected to transit through the VPN link (e.g. with MQTT Client Component to a remote MQTT broker).

• reboot_timeout (Optional, Time): The amount of time to wait before rebooting the device when the remote peer is unreachable. Can be disabled by setting this to 0s. Default to 15min.

• require_connection_to_proceed (Optional, boolean): Set to true to wait for the remote peer to be up before continuing to boot the device. Default to false.

  This can be used to delay the initialization of components that use the VPN tunnel as long as the VPN isn’t ready. For example if you are using MQTT Client Component to reach a remote broker you may experience boot freeze just after the setup of MQTT because it waits for the broker to be reachable, but the connection cannot be established until the VPN link is active too. To bypass such deadlock set this parameter to true in order to not initialize MQTT until the remote peer is up.

• update_interval (Optional, Time): How often to check the connection status and the latest handshake value. Default to 10s.

• id (Optional, ID): Manually specify the ID used for code generation.

Static routes and outgoing connections

Currently there is no way on ESP devices to configure static routes for network interfaces, so the peer_allowed_ips list is used only to allow (or drop) packets that pass through the VPN tunnel, not to define static routes for remote hosts.

The routes are implicitly added by the configured netmask and only packets with destination inside the same network defined by address/netmask will be routed to the tunnel.

This means that the user has to tweak the 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.

Let’s explain with some examples:

ℹ️ Note

Setting the netmask to 0.0.0.0 has the effect of routing through the VPN link any traffic. It is like having set the wireguard interface as the system default.

Sensors

Here after the sensors available for this component.

Status Binary Sensor

This binary sensor tracks the connection status (online/offline) of the remote peer.

# Example configuration entry
binary_sensor:
  - platform: wireguard
    status:
      name: 'WireGuard Status'

All options from Binary Sensor can be added to the above configuration.

Enabled Binary Sensor

This binary sensor tracks if WireGuard® is enabled or not.

# Example configuration entry
binary_sensor:
  - platform: wireguard
    enabled:
      name: 'WireGuard Enabled'

All options from Binary Sensor can be added to the above configuration.

Latest Handshake Sensor

This sensor reports the timestamp of the latest completed handshake.

# Example configuration entry
sensor:
  - platform: wireguard
    latest_handshake:
      name: 'WireGuard Latest Handshake'

All options from Sensor can be added to the above configuration.

Address Text Sensor

This sensor exposes to the frontend the configured address.

# Example configuration entry
text_sensor:
  - platform: wireguard
    address:
      name: 'WireGuard Address'

All options from Text Sensor can be added to the above configuration.

Actions

The following actions are available.

wireguard.disable

This action drops down the active VPN link (if any) and disables the component.

on_...:
  then:
    - wireguard.disable:

The lambda equivalent is id(wireguard_id).disable().

ℹ️ Note

To disable WireGuard® since device boot you can execute this action in the on_boot step.

wireguard.enable

This action enables the component and starts the connection to the remote peer.

on_...:
  then:
    - wireguard.enable:

The lambda equivalent is id(wireguard_id).enable().

Conditions

The following conditions are available.

wireguard.enabled

This condition checks if WireGuard® is currently enabled or not.

on_...:
  - if:
      condition: wireguard.enabled
      then:
        - ...
      else:
        - ...

The lambda equivalent is id(wireguard_id).is_enabled().

wireguard.peer_online

This condition checks if the remote peer is online.

on_...:
  - if:
      condition: wireguard.peer_online
      then:
        - ...
      else:
        - ...

The lambda equivalent is id(wireguard_id).is_peer_up().

Remote peer setup

There are many different ways for installing and configuring WireGuard® on servers, home servers or general host. It depends on the platform and on the operating system in use.

You can start reading the official documentation to have an overview of what it is and on how to install it system wide for common operating systems. Read the thread at Home Assistant Community Add-on: WireGuard if you intend to install it through Home Assistant. Plase note that securely setting up a VPN requires some networking experience, you will need to open router ports and possibly use custom commands to redirect traffic.

Once everything is configured you should be able to add the device to Home Assistant. See next section.

Connecting to remote Home Assistant

The ESP device should interact with remote Home Assistant, across the VPN link, as it is on the local network but probably the initial auto discovery will not work and you have to add the device manually.

These are the steps:

1. go to the Home Assistant “Integrations” page
2. click on the “Add Integration” button (bottom right corner)
3. select “ESPHome” from the list
4. insert the configured IP address as the host name

The device should now be linked to your remote Home Assistant.

ℹ️ Note

If you have issues linking the ESP device try setting the use_address parameter of the WiFi Component to the value of the address configured here.

See Also

• Time Component
• SNTP Time Source
• Automation
• WireGuard® official website
• Home Assistant Community Add-on: WireGuard (also on GitHub)