WHR reverse tunnel add-on v2 with TLS pass-through - testers needed

I have been iterating on this add-on for quite a bit by now, trying to achieve a balance between simplicity, security and feature completeness.

About

In short, this add-on allows secure access to your Home Assistant without having public IP, port forwarding or setting up HTTPS. This is achieved by opening a reverse tunnel to the my.webhookrelay.com servers and allowing TLS traffic to go through our servers without termination straight to your Home Assistant instance.

Main features/characteristics:

  • TLS pass-through mode - traffic is fully encrypted on your own device and stays encrypted till it reaches your browser. Nobody can spy on you.
  • Custom domains - if you have, use your own domain. Example is given with DuckDNS provider since it offers free subdomains + easy to use API.
  • Lightweight - add-on is written in Go, arm image size is 5MB, barely uses any CPU/RAM.
  • Optional TLS termination by the add-on - for the sake of simplicity for the user, add-on can terminate TLS connections so your Home Assistant doesn’t have to have configured HTTPS, but you are more than welcome to do it. Just specify https:// in tunnel destination.
  • Integrated Let’s Encrypt + DuckDNS support - add-on can retrieve Let’s Encrypt certs for your DuckDNS subdomain and configure them to work with the reverse tunnels. Traffic gets encrypted end-to-end and your browser remains happy :slight_smile:
  • Multiple tunnel support - get tunnels for your Home Assistant, Node-RED or anything else.
  • One-way webhook forwarding - if you don’t want to expose your services to the internet, you can use one-way webhook forwarding that only allows inbound traffic. This is only useful for webhooks.

Pricing (after 3 months test-drive)

I have several users testing this add-on already, but would like to have a bit more. Testers will get 3 months of free access. After that my plan is to make DuckDNS domains available in the basic plan which will cost $4.5/month for 3 tunnels.

Installation

You can find a short tutorial here: https://webhookrelay.com/blog/2018/10/12/hassio-tls-tunnels-duckdns/. After registering for a free account, drop me an email ([email protected]) and I will enable TLS and custom domains.

Config example

{
	"key": "your-webhookrelay-key",
	"secret": "your-webhookrelay-secret",
	"forwarding": [
	  {
		  "bucket": "ha",
		  "destination": "http://127.0.0.1:8123"
	  }
	],
	"tunnels": [
		{
			"name": "ha",
			"destination": "http://127.0.0.1:8123",
			"protocol": "tls",			
			"domain": "your-domain.duckdns.org"			
		}	
	],
	"duck_dns": {
		"token": "your-duckdns-token",
		"accept_terms": true
	},
	"tunnels_enabled": true,
	"forwarding_enabled": false
}

Config example with Home Assistant doing TLS termination can be found here.

Add-on permissions

It currently requires ssl mapped and host_network = true, however they aren’t really required in the default mode. Add-on persists retrieved certificates in /data directory and with host network disabled you can access home assistant by setting destination to http://homeassistant, although it does make Node-RED unreachable (haven’t looked whether add-ons get networks configured to facilitate communication between each other).

Troubleshooting

Currently add-on logs a bit more than it will but there are a bunch of “info” level messages, such as contacting DuckDNS, Let’s Encrypt. I have noticed that quite often DuckDNS API lookup fails, not sure whether it’s my pihole or something else but I have added retries. After the first successful update those errors don’t really matter.

  • Don’t use with DuckDNS add-on since it would be changing IP address to whatever it thinks it is instead of the tunnel public endpoint.
  • If you Home Assistant has HTTPS, destination should be https://127.0.0.1:8123

I got a bit too keen and signed up without reading on about the free three month trial! Whoops.

Well, I installed the addon and think I have all of the settings correct, but I’m not able to access through my duckdns address (I have disabled the duckdns addon). I can access it through:

.webrelay.io/states

Any ideas?

If I am correct after my little investigation in finding your account, it seems that you haven’t specified custom domain. Can you share your add-on config? Just remove your webhookrelay access tokens and duckdns token + domain that you use :slight_smile:. Email to [email protected] is also fine.

If your config looks like this:

{
  "key": "your-webhookrelay-key",
  "secret": "your-webhookrelay-secret",
  "forwarding": [
    {
      "bucket": "ha",
      "destination": "http://homeassistant:8123"
    }
  ],
  "tunnels": [
    {
      "name": "ha",
      "destination": "http://127.0.0.1:8123/",
      "protocol": "tls",
      "domain": "your-duckdns-domain.duckdns.org"
    }
  ],
  "duck_dns": {
    "token": "your-duckdns-token",
    "accept_terms": true
  },
  "tunnels_enabled": true,
  "forwarding_enabled": false
}

Then probably delete the tunnel in https://my.webhookrelay.com/tunnels and restart the add-on.

OK, cool.

{
  "key": "somekey",
  "secret": "somesecret",
  "forwarding": [
{
  "bucket": "ha",
  "destination": "https://192.168.0.200:8123"
}
  ],
  "tunnels": [
{
  "name": "autopilot",
  "destination": "https://192.168.0.200:8123",
  "protocol": "tls",
  "domain": "somename.duckdns.org"
}
  ],
  "duck_dns": {
"token": "sometoken",
"accept_terms": true
  },
  "tunnels_enabled": true,
  "forwarding_enabled": false
}

I’m not sure what the 127.0.0.1 is and if I should be using it, and where. Thanks for your help!

127.0.0.1 is the local interface that services can talk to each other. Since both webhookrelay agent and home assistant are running on the same machine, it should be http://127.0.0.1:8123. If you want the add-on to get the DuckDNS certs and do the TLS termination, your home assistant should locally be accessible through http:// and not https://.

OK, I made my HA accessible with http (not https) and then changed the config to:

{
  "key": "somekey",
  "secret": "somesecret",
  "forwarding": [
{
  "bucket": "ha",
  "destination": "http://192.168.0.200:8123"
}
  ],
  "tunnels": [
{
  "name": "autopilot",
  "destination": "http://127.0.0.1:8123",
  "protocol": "tls",
  "domain": "somename.duckdns.org"
}
  ],
  "duck_dns": {
"token": "sometoken",
"accept_terms": true
  },
  "tunnels_enabled": true,
  "forwarding_enabled": false
}

Still doesn’t work and now I can’t access it even through *.webrelay.io

have you deleted existing tunnel from https:/my.webhookrelay.com/tunnels which was *.webrelay.io instead of *.duckdns.org?

OK, great - that worked!

Now, as for adding being able to access other parts of HA - how does one do that? For example, I need google home to be able to access somename.duckdns.org/api/google_assistant. I also want to be able to access other add ons from the net, like somename.duckdns.org:8443 and somename.duckdns.org:3218.

Is it just a matter of creating another tunnel (I unsuccessfully tried that)? Or something else? Thanks heaps for your help to date!

Yeah, it should be additional tunnels. I and other users just create 1 or more tunnels with strategy:

somename-ha.duckdns.org - > http://127.0.0.1:8123
somename-nodered.duckdns.org - > http://127.0.0.1:1880

On the browser it will always be just HTTPS default port, tunnel destination doesn’t have to match that, routing is being done based on the domain/subdomain. So if you have a Node-RED running on port 1880, then config would be:

{
  "key": "somekey",
  "secret": "somesecret",
  "forwarding": [
{
  "bucket": "ha",
  "destination": "http://192.168.0.200:8123"
}
  ],
  "tunnels": [
{
  "name": "autopilot",
  "destination": "http://127.0.0.1:8123",
  "protocol": "tls",
  "domain": "somename.duckdns.org"
},
{
  "name": "nodered",
  "destination": "http://127.0.0.1:1880",
  "protocol": "tls",
  "domain": "somename-nodered.duckdns.org"
}
  ],
  "duck_dns": {
"token": "sometoken",
"accept_terms": true
  },
  "tunnels_enabled": true,
  "forwarding_enabled": false
}

not sure about the google assistant, is it running on the same port as HA?

Ok, I’ve sent you an email to not clog up this thread any more…