Router setup

Home Assistant OS and its Add-ons (like VPN or DNS server) require changes to your local network. Most home routers should support these, although each brand's user interface and feature-set are different. Due to this, I'll only be able to give a bit of guidance on what needs to be set.

I'm going to base this guide on a router running OpenWrt, an open-source Linux-based operating system primarily used on embedded devices to route network traffic. OpenWrt replaces the factory firmware and provides a unified user interface, third-party package management, and a set of advanced routing features to a wide range of devices. Check out the list of supported devices in the OpenWrt Table of Hardware if you would like to install it too.

Table of contents

Initial steps

Re-addressing local network

Post HA installation

IP reservation (Static DHCP lease)

DNS server

Port forwarding - VPN tunnel

Initial steps

Start with finding out your router's IP address and enter it into a browser window to bring up the router's user interface. If the username and password are unknown, search for the keywords: "<ROUTER MAKE AND MODEL> default login" or check the label on the router's back. OpenWrt's default IP address is 192.168.1.1, and the username is root with a blank password. The login page hosted on http://192.168.1.1 looks like this:

Once logged in you'll get an overview of the current Status:

Re-addressing local network

Update: This step is not necessary, you can use your own IP range instead of 192.168.9.0 used in this guide.

By default, most home networks use the Class C private IP range of 192.168.0.0/24 or 192.168.1.0/24. When a VPN client connects to Home Assistant from a network that uses the same network range it creates routing issues where either traffic intended for Home Assistant is not routed into the VPN tunnel or local devices become inaccessible. The easiest solution is changing the IP range of your home network to a less-common range.

Navigate to Network - Interfaces and select the Edit button of the LAN interface. (On other routers look for the keywords: Network, LAN , Local network, IPv4 address, address range)

In this example, I'm going to be using the 192.168.9.0/24 network range, where the connected devices can get an IP between 192.168.9.1 - 192.168.9.254. You may select a different network address by changing the third number(9) between 2 - 254 (Avoid the common 0 and 1).

After applying the change you will need to force a DHCP update or disconnect and reconnect all network devices to ensure they receive a new IP address from the updated range. The router's web interface address will also change, update the URL in the browser and reload the router's interface.

Post HA installation

The below steps require Home Assistant OS already installed and some Add-ons already configured (I'll link back to certain sections of this guide during the setup).

IP reservation (Static DHCP lease)

When using DHCP IP reservation, you're telling your router to assign the same IP address to a specific device whenever that device connects to the network. This is done by pairing the device's physical address (MAC address) to an IP. Create the following reservations in the router configuration:

192.168.9.99 - Hypervisor: The physical server hosting the Home Assistant OS virtual machine
192.168.9.100 - HomeAssistant: The Virtual Machine running the Home Assistant OS image
192.168.9.101 - Gbox420: The ESP8266 chip connecting the Gbox420 Arduino sketch to the local network

The easiest way to figure out the MAC address of a device is from the router's Status page, or under Network - DHCP and DNS - Static Leases

Under Network - DHCP and DNS - Static Leases use the Add button to add new static leases with an infinite lease time:

The ESP-link firmware displays the MAC address of the ESP8266 chip on the WiFi Station tab:

VirtualBox displays the MAC address of a Virtual Machine under: Settings - Network - Advanced - MAC Address

DNS server

Requires AdGuard Home add-on installed! Since we are going to use Home Assistant as a DNS server it is recommended to distribute its IP address to all DHCP clients using the router. Only do this after installing the AdGuard Home Add-on in Home Assistant, else devices on your network will not be able to resolve DNS names!

DNS forwarding
Forwarding DNS requests received by the router is a quick and easy way to divert all DNS traffic to a specific server without making changes to each network device individually.
Under Network - DHCP and DNS - General Settings it is possible to list DNS servers to forward requests to:

Temporarily you can enable Log queries to print DNS lookups to syslog. To view syslog connect to the router's IP using SSH (authenticate as root user + router password) and run the following command: logread -f. Now if you do a DNS lookup it should get logged:

In case Home Assistance or the AdGuard add-on crashes and you need to quickly fix DNS lookups you can change the IP to one of the following public IP addresses:
Cloudflare: 1.1.1.1, 1.0.0.1 ; Google Public DNS: 8.8.4.4, 8.8.8.8 ; Quad9: 9.9.9.9, 149.112.112.112.

After Home Assistance is working again you need to remove the temporary forwarding to ensure all DNS traffic goes through AdGuard Home.

DHCP option 6
Using DHCP option 6, we can pass one or more DNS server address(es) to devices on the network when they request an IP address. Not all routers support this option.
Open the Network - Interfaces page, and edit the LAN interface:

Select DHCP Server - Advanced settings. Under the DHCP-Options specify the DHCP option for DNS servers (6) and list the IPs to distribute as DNS servers:
6,<HomeAssistant IP>,<Router IP>

Normally we need to direct all DNS traffic to Home Assistance since we will be rewriting DNS entries using AdGuard. The reasons for adding the router's IP as a secondary DNS server are:

Android tends to add a Google Public DNS (8.8.8.8) as a secondary DNS server if the DHCP server does not specify one
The router is configured to redirect DNS traffic to the Home Assistant by default
In case Home Assistance goes down the Router can be temporarily reconfigured to direct traffic to a public DNS server

Changing the DNS server
This option is supported on all routers, check out this howtogeek.com article on Changing Your DNS Server. Not needed if DNS forwarding and DCHP Options are supported and configured.
Open the Network - Interfaces page, and edit the WAN and WAN6 interfaces:

Un-check the "Use DNS servers advertised by peer" option, and add the Home Assistant server's IP as a Custom DNS server (Do not forget to click the green + after entering the IP)

Port forwarding - VPN tunnel

Home Assistant acts as a VPN server and clients on the Internet need to reach it. We are going to open a single port on the router's WAN interface and direct incoming traffic to the Home Assistant server. For a general overview check out this noip.com article on Port Forwarding.

Setup a Port Forward rule on the local router from Network - Firewall - Port forwards tab by clicking the Add button:

Use the UDP protocol and external port 51820, the source of the traffic is the WAN and the destination is the LAN interface. Redirect the incoming traffic to the Home Assistant server's IP address and set the internal port to the listening port of the WireGuard add-on (default 51820).

Google Sites

Report abuse

Router setup

Initial steps

Re-addressing local network

Post HA installation

IP reservation (Static DHCP lease)

DNS server

Port forwarding - VPN tunnel

Project made by GrowBoxGuy