Home Assistant Remote Access networking

I’ve written this guide for the documentation pages of the Home Assistant iOS companion app. As I’m rather proud of them I’m republishing the guide here. Jan

Companion app networking

Having your Home available anywhere and everywhere you go is important, whether you forgot to turn off the stove or you want to check the camera views because of an alert.

Because we want your smart home to be private and secure on the web, many parts of the puzzle need to align just right so everything works as you expect. This guide aims to help you understand the requirements, some of the complexities and our recommended typical solutions to setting up network access to your Home Assistant instance:

The basics: How the app talks to your Home Assistant

In order for the app to talk to HA, it needs to know its address. Just within your home network you might know that your Home Assistant is on an IP like 192.168.1.4 and listening on port 8123. If you use Hass.io and haven’t changed any of the defaults, Home Assistant will also be reachable at http://hassio.local:8123.
This is all fine and will work perfectly well as long as you never take your phone or tablet outside your home, but what if you do?
The easiest way is to subscribe to Nabu Casa Cloud for the small monthly fee of $5 US, which will solve all this for you and you can (almost) stop reading here, as well as supporting further development of Home Assistant. Nabu Casa Cloud acts as a “smart” proxy on the internet, tunnelling your frontend in an encrypted manner from your home to your phone, regardless where you are and without requiring opening your home network to inbound traffic from the internet.
If you don’t want to use Nabu Casa Cloud (which is fine, but you should still subscribe and enjoy the warm feeling of supporting Home Assistant), you need HA to be accessible from the internet. This requires opening a port on your router and getting a name for your Home Assistant on the internet. While it is possible to have your HA use Port 8123 internally and have your router do a port-forwarding from say the default https port of 443 to 8123, we recommend you NOT do this for reasons of simplicity which we will explain later. You also need a name for your Home Assistant as hassio.local is a private domain suffix that does not exist on the internet.

Dynamic DNS

Most non-business internet connections have at least one of two drawbacks: Your internet service provider typically does not give you a static IP (meaning the public IP address your modem/router is assigned will change every once in a while or even every 24 hours) and some ISPs don’t even give you a “real” IP address as they do not have enough addresses to give out. This last scenario is very common on cable providers and especially in Asia/Pacific. If your ISP says they use Carrier-grade NAT (CG-NAT) or something like Dual Stack lite (DS-lite) you likely will have this problem. If you’re impacted please see the CG-NAT and IPv6 addendum.
For dynamic, public IP addresses the solution is simple: Typically users choose a dynamic dns service such as duckdns.org which will create a unique name (e.g. my-home.duckdns.org) that is supported to be updated via your router to always point to your public address. If you have created the port-forward of TCP 8123 on your router’s public interface to TCP 8123 on your internal Home Assistant IP (say 192.168.1.4), your Home Assistant is now available on the web. You could declare victory at this point and stop but don’t – because everything at this point is unencrypted and we want you to enjoy HA in a private, secure manner.

Hairpin NAT

At this point of setting up we need to check one capability of your router: Hairpin NAT (otherwise known as NAT reflection or NAT loopback). What this means is the ability of your router to mirror a request from its inside (LAN) interface to its outside (WAN) address back to an internal IP address (in this case, your Home Assistant), thus reflecting or hairpinning the traffic. It’s easy to check if this works: Just open a browser on your phone or PC while connected to your home network and opening http://my-home.duckdns.org:8123 – if it works, you have hairpin NAT working and can go on to the next section. Most current routers will support NAT hairpinning out of the box, there are however some routers (especially if you got your router from your ISP) that do not have this ability or have it disabled. If this is the case, you need to check if you can enable it on your router or, if you can’t, you will need to set up Split Brain DNS.

Securing the connection

We’ll stay with our DuckDNS example. Using http://my-home.duckdns.org:8123 works, but anyone could be reading your traffic. Let’s change that! The DuckDNS Hass.io add-on will create a free, trusted and valid LetsEncrypt SSL certificate to use on your Home Assistant. Just follow the installation instructions here and here and you will have secure, public access to your Home Assistant. What’s great about using the DuckDNS add-on is that it uses the LetsEncrypt DNS challenge, whereby during requesting the certificate it proves “ownership” of the domain by creating a temporary DNS record. If you use a different DNS provider other than DuckDNS, you can use the LetsEncrypt add-on for Hass.io which supports proving ownership of the name either via the DNS or the http challenge. The latter requires port-forwarding TCP Port 80 on your router to your internal Home Assistant IP on TCP Port 80.

With Hairpin NAT working and SSL on your DNS domain you can now access Home Assistant securely both on the internet and at home and you should add base_url: my-home.duckdns.org:8123 to the http: section of your configuration.yaml. This is not strictly necessary but will help with auto-detection during onboarding of the iOS app, as the app will know where and how to reach your Home Assistant.

Split Brain DNS

So what’s this split brain DNS (also known as split horizon DNS, split-DNS) thing and why would I need it? If your router doesn’t do hairpin NAT, you still need to access your Home Assistant via the public DNS name, e.g. my-home.duckdns.org. Why is that? Because valid encryption via https and SSL certificates only works for public DNS names. What this means is that the certificate name on your server needs to match the DNS name you enter in your browser or app. This is fine with hairpin NAT available but becomes an issue when it’s not. In this case you need to “split” the answer your browser/app gets when it looks up the IP address behind my-home.duckdns.org – you need one answer for devices on your home network that points to the internal IP address of your Home Assistant (e.g. 192.168.1.4) and another answer for when you’re out and about [e.g. 104.25.25.31.
The easiest solution to this is to use the Hass.io add-on AdGuard Home. This can also be set up on some routers (e.g. pfSense or UniFi Security Gateways) but we’ll continue on using our example guide with the tools provided via Hass.io: So you’ve now installed the AdGuard Home add-on and changed the DNS server on your router DHCP settings to the address of your Home Assistant. You should now go to the AdGuard Home setting page in your Hass.io panel and there go to Settings -> DNS settings, then scroll down to the bottom where you have a box titled: DNS rewrites
Here you click Add DNS rewrite and enter your my-home.duckdns.org and the internal IP 192.168.1.4 of your Home Assistant, followed by clicking on save. What happens now is that all DNS queries for the address my-home.duckdns.org from inside your home network will be answered by AdGuard via its own rewrite table, thus pointing toward the internal address of your Home Assistant instead of asking public DNS servers on the web which will all answer with the public IP of your router.
Even if you don’t need split brain DNS, you may also want to set this up as it will enable you to access Home Assistant via it’s public name even when your internet connection is down and hairpin NAT won’t work. One less dependency on the Cloud!

Setting up the iOS app

If you’ve followed all our advice, your app should find your Home Assistant instance automatically during onboarding when connected to your home wifi network. You can also go through onboarding anywhere you’re connected to the internet by manually entering https://my-home.duckdns.org:8123 and the setup will finish with that address in the External URL field in the app connection settings. There should be no need to enter an internal URL as the same address will work regardless of where your phone is connected.
If you want to (or have to) use Nabu Casa Cloud, there are two more steps required:
– In iOS settings, set location access permissoin for Home Assistant to Always. This is required because starting with iOS 13, Apple will only let apps with such permission have access to the wifi SSID which is used by the app to determine whether to use internal or external URLs.
– Once permission is given, add your Home Assistant address to internal URL (if you come from the top of this article, this could be http://hassio.local:8123
– If you’ve set up Nabu Casa Cloud in your Home Assistant the checkbox to “Connect via Cloud” should now become available. Once you activate the checkbox, external URL will become deactivated.

Addendum: CG-NAT

If your ISP doesn’t give you a public IPv4 address you’re down to basically only two solutions: You can call your ISP and ask if they can give you a real address or if there is an upgrade for your connection available (oddly enough, asking nicely will work with many ISPs out there) or use Nabu Casa Cloud.

Addendum: IPv6

Since IPv6 has been rolling out for the last 20 years, chances are that along with an IPv4 address your home network will also have been provided with IPv6 addresses from your ISP. So your Home Assistant host may have it’s IPv4 address of 192.168.1.4 as well as an IPv6 address of e897:5571:5f66:21dc:51c1:28d8:3bdc:6724. Here’s where our advice for not changing the TCP port you forward to Home Assistant comes in:
– Home Assistant will listen for traffic on 192.168.1.4:8123 and [e897:5571:5f66:21dc:51c1:28d8:3bdc:6724]:8123
– If you really want to future proof your setup, you will have two DNS records for my-home.duckdns.org: An A-record pointing to your routers public IPv4 address which will be port-forwarded to your HA hosts internal address and an AAAA-record, which points directly to the IPv6 address of your HA host. Now when you access your HA remotely either protocol could be used, since all you’re entering will be https://my-home.duckdns.org:8123. If you had changed the Port on your Router to the https default 443, the connection would now fail if you suddenly ended up with a working IPv6 setup as nothing is listening on [e897:5571:5f66:21dc:51c1:28d8:3bdc:6724]:443.

Addendum: Reverse Proxy via NGINX

There are cases when having Home Assistant serve https is impossible or incompatible with some of your devices. This can be especially true with ESP-based low power IoT hardware that communicates via RestAPI and just doesn’t have the horsepower to do the SSL encryption. One example is the konnected.io Integration which requires Home Assistant to be reachable via http.
So to accomodate this and still have encryption for external access, we use a reverse proxy like NGINX. What a reverse proxy does is to act as an intermediate for your clients (Browser or App). The client talks to the reverse proxy securely via https and the proxy passes through this traffic to Home Assistant over an unencrypted http connection. Staying with our Hass.io example, we’ll assume you have already set up DuckDNS and LetsEncrypt. You should now install the Hass.io add-on NGINX Home Assistant SSL proxy and configure it according to the docs.

In your configuration.yaml file the following changes are needed:

http:
  use_x_forwarded_for: true     # To ensure HA understands that client requests come via reverse proxy
  trusted_proxies:
    - 172.30.32.0/23            # In Hass.io we need to add the Docker subnet
    - 127.0.0.1                 # Add the localhost IPv4 address
    - ::1                       # Add the localhost IPv6 address
  base_url: my-home.duckdns.org # Note we no longer have a :8123 Port here
  # Uncomment or remove the SSL certificate lines:
  # ssl_certificate: /ssl/fullchaim.pem
  # ssl_key: /ssl/privkey.pem

Once that’s done your router’s port-forwarding should be TCP 443 to your Home Assistant internal IP 192.168.1.4 Port 443. Do NOT create a forward to 192.168.1.4 Port 8123 as that is now unencrypted http and should only be accessible from your local network.
You can now access your Home Assistant via https://my-home.duckdns.org both internally and externally while having http://192.168.1.4:8123 available to be used as unencrypted endpoint for things like konnected.io.
Note: If you don’t use the NGINX Hass.io add-on but instead roll your own, please ensure that websockets support is enabled.

Related Post

Case of the missing Outlook SSOCase of the missing Outlook SSO

If you’re in IT you certainly know this scenario: There’s something in your environment you just can’t get to work the way you want, you’ve spent countless hours reading documentation, googled community forums and fiddled endlessly with settings in order to make it work. It’s not a showstopper and there is a workaround or even just a single prompt that only shows up every once in a while so you can’t justify powering through the issue until it is done, but you return to it every so often. Then it happens, you’re on a completely unrelated thing and reading through docs or configuring settings and then you stumble upon it, a small textbox that explains your issue and how to fix it.

This just happened to me. I’ve been trying to get SSO (Single Sign On) to work for our corporate PCs but haven’t had any luck whatsoever in years of trying. No matter what I did, we always still got prompted to enter credentials for Outlook and Skype for Business. Today I learned why:

Like many organizations, we’re using Office 365. We also use AzureAD Connect to sync our on-premises Active Directory to the Microsoft Cloud and have set it to enable SSO for our users – which works really well for everything but Outlook. The issue of logging in to Skype for Business went away when we migrated to the newer Teams client but Outlook remained a thorn in my side – one I just couldn’t get myself to figure out.
Lately, we have been trying to roll out Microsoft’s Security Defaults for our AzureAD environment and activating Multi-Factor Authentication (MFA) for all our users. The issue I ran into here was that when I enabled the AzureAD Security Defaults, none of my users were able to log in to Outlook on their PCs anymore. Searching through docs for this put me on the right track: For some reason, our Outlook installs were using Legacy Authentication. Some Google-Fu put me on to registry keys I was supposed to add to Enable modern authentication in Outlook – to no avail.
Careful reading of the docs however put me on to the source of my pain:

As we’ve been using Office 365 for a long time, this was us! Mind you, all documentation available on the web is (of course…) written agains the current defaults, which have modern authentication turned on.
Quickly jumping into Powershell solves this:

$UserCredential = Get-Credential
$Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://outlook.office365.com/powershell-liveid/ -Credential $UserCredential -Authentication Basic -AllowRedirection
Import-PSSession $Session -DisableNameChecking

Set-OrganizationConfig -OAuth2ClientProfileEnabled $true

Remove-PSSession $Session

That’s it. Once I set this, Single Sign On to Outlook just worked. MFA just worked. And I have one less thing on the to-do list that I’ve been visiting over and over for years.

-Jan

The perfect home networkThe perfect home network

  1. It’s been a busy year and some of the things I’ve been involved in warrant writing about. So here we go!

We’ve moved to a new home and it’s been quite a project. But let’s settle for the really important stuff: The new home network. Winking smile Having bought into the building just early enough, we took the opportunity to adjust the wiring specifications just slightly from what was luckily already a pretty decent setup. There were plenty of electrical outlets, coax cable in every room and phone lines part of the plans. We only added a few electrical outlets so we would never have to run any power cables around corners (I hate cable clutter!) and then went to town on the data cabling:

I’m a big fan of speed. Especially where networks are concerned. So CAT6 Ethernet was the minimum requirement. While we’ll come to wi-fi later, nothing I’ve seen commercially available will beat a wired connection. So we put at least two RJ-45 sockets into every room.

WP_20161218_16_54_37_Pro_LINot knowing where we’d put the TV on the wall, we set up two walls in the living room for easy placement. To me this means putting all the necessary outlets (Power, Cable TV and Ethernet) right up the wall so they are hidden behind the TV when that is mounted. This way all the cables just vanish from sight. As we don’t need two TVs in the living room, we have the second row of outlets hidden behind a picture frame.

If there is one thing I’ve learned from experience: There is no substitute for planning when it comes to setting up a network. Getting the physical layout and architecture right the first time will save you a lot of money, time and nerves in the long run. So I did not want to compromise when it came to my home setup.

WP_20161218_17_07_55_Pro_LIAll CAT7 cables run into our storeroom. There they meet up with the coax TV cable which currently serves as our ISP line.

At the same location I also have the option to access the POTS wiring if I wanted to switch to xDSL. And there is a proper 19” network cabinet. I won’t call it a rack as it is only 9U – then again it fits all the equipment I’ll ever need it to host.

WP_20161218_17_06_47_Pro_LI

First of all, you’re looking at a Rittal FlatBox DK 7507.110. The enclosure is wall-mounted with just enough space for cleaning (basically making sure our Roomba will fit with no issues).

I use an EQUIP 333293 PDU with some cable modifications: I ran the power cable that enters the enclosure directly into the PDU, replacing the original power cable. At the same time I connected the grounding wires that connect all of the metal parts of the enclosure to the grounding wire that is part of the house electrical installation.

I use an EQUIP 326416 16 port CAT6 patch panel – I only need 12 Ports but I wasn’t able to find a 12 port 19” panel. All CAT6a panels I looked at were 24 ports and I preferred the centered 16 ports on this panel as I’m using small switches with ear extensions. Speaking of switches…

WP_20161218_17_05_57_Pro_LIWe have two 10 port Cisco Small Business switches: One SG300-10 as well as an SG300-10PP for 802.3at POE+. I already had experience with the SG300 line of switches from multiple jobs and so far I can absolutely recommend them for any small business  / edge switching / home lab use. They basically do everything you can ask of a switch right now up to and including Layer 3 routing. But most importantly, the SG300-10PP is the only rack-mountable switch I was able to find with POE+ that is fanless. It has a 60 Watt power budget which for my use cases is plenty.

Completing the network are my cable modem, a Ubiquity UniFi Security Gateway (USG) and a Ubiquity UniFi CloudKey. Then there is my trusty old Netgear ReadyNAS Pro Business – slightly modified with upgrades to the CPU, RAM and fans. The last part being essential: Replacing the stock fans with some Noctua fans was probably the best upgrade to that system.

I’m considering replacing the current NAS with a smaller 4-bay model in the future. My needs here are relatively simple: All I need is lots of storage along with support for SMB, DLNA and Wake-On-LAN. With progress in ARM based storage devices, I’m seriously thinking about taking the plunge just to get the power needs down. Cooling hasn’t been an issue so far but the room does warm noticeably when the door is closed – as was to be expected with it having virtually no ventilation whatsoever.

So on to the wireless setup: Having the best wife in the world, I was actually gifted a Ubiquity UniFi AP AC PRO for my last birthday, right off my Amazon wish list. Only there was a problem. Several actually:

– The dashboard is kind of addictive. The amount of information it can give you – without messing about with SNMP, MIB files etc. – is just amazing. I love solutions that just work.
– As with any entrance drug, UniFi really only works when you set up the whole shebang. So I picked up a USG security gateway to get insight into my network traffic on the WAN side.
– This being my place, any dead spots in coverage or drop-off in throughput could not be tolerated. So the single AP was soon joined by two of it’s brothers.
– I’ve come to appreciate single-use appliances. Things designed to do one thing, and one thing only. And do it well. So I’m running the UniFi controller on the purpose built UniFi CloudKey. I originally thought about using my Raspberry Pi but then remembered how much I actually hate caring and feeding a Linux system on a day-to-day basis.

What I ended up with was this:

WP_20161217_21_05_29_Pro_LI

So how did I set up the Wi-Fi? I’ve been using the UBNT community forum to read up on what works and best practices. Basically the logical network I’m running is rather simple: There is no point in using fancy things like management VLANs around my LAN and while I might set them up for the home lab, everything is just a flat class C private subnet (my provider hasn’t figured out yet how to give me an IPv6 prefix – I wager it’ll take them longer to get that done then it takes Chris Büchler (of pfSense fame and now working at Ubiquity on the Routing & Switching products) to implement IPv6 on the UniFi controller and USG router.

I currently have an open guest network using the UniFi controller to act as a HotSpot gateway using vouchers (Not happy with the open nature of this network, any help in setting up HotSpot 2.0 to get encryption for guests without having to hand out WPA-keys would be appreciated).

And this is how it looks:

2016-12-18This is a view of the UniFi controller running on my home network.

Where things get tricky is the map view. This may help with planning the deployment of hotspots, you’ll see it’s always a good idea to check with reality:

 

2016-12-18 (8)This is just the plain view of locations of the access points. WP_20161217_21_23_55_Rich_LI

What I want is good signal in all rooms as well as fast speeds in all locations that are commonly used by me.

All the UniFi AP AC Pro’s are wall-mounted.

Let’s take a small detour into the ABC’s of Wi-Fi networking:

2.4 GHz is for coverage. WP_20161217_22_12_36_Pro_LI
5 GHz is for speed.

There are only 3 non-overlapping 2.4 GHz channels (1, 6, 11) at 20 MHz channel width. At best this gives you 300 MBit/s linkspeed with a two antenna setup. As 2.4 GHz Wi-Fi will penetrate further, be a good neighbor and don’t use wider channels. Also it is a good idea to turn down the power of the AP so as not to cause interference where you don’t actually need you Wi-Fi coverage anymore.

At 5 GHz, *if* you can use DFS Channels, there are up to 4 non-overlapping channels of 80 MHz bandwidth each. This gives you up to 866 MBit/s linkspeed with two antennas. It is very rare to come across a Wi-Fi client with more than two antennas. Unless you only have drywall, you can forget about getting a useful signal more than one wall away.

There are plenty of rules of thumb about this but nothing beats actually measuring it!

2016-12-18 (10)

Using the free tool Netspot, I made this coverage map of my apartment. In this screenshot I’m showing just the 2.4 GHz coverage. As you can see, the tool gives slightly different locations for the Access Points. It puts them where the signal is strongest – which depending on things like the signal bouncing off surfaces might be quite a bit off: See the bottom right AP which the measurements put right in front of the metal door to the elevator.

On 2016-12-18 (9)the 5 GHz front things look a lot colder. As expected, there is only really a fast connection in the rooms where we actually put the APs. Then again we don’t really need the speed in our guest room.

So that’s it for this project. Please tell me what you think, any suggestions where I can improve or whatever else comes to mind!

-Jan