New Add-On: Cloudflared

Hi Everyone,

I recently started working on my first add-on “Cloudflared” and would like to share it with all of you.

Why?

When I got a new domain name, I started working with Cloudflare. Up until then, I used Duck DNS to access my HA instance via opening ports in my router, which I did not really like. Recent announcements from Cloudflare regarding their new Zero Trust Platform Teams, made me check them out in detail. I realised that they offered a great way of securing your applications and connecting them to their servers by leveraging their tunnel service Cloudflare Tunnel. So, I device to try to use this service for my HA instance.

What?

I created this Cloudflared add-on. I also created an Add-On repository that you can find here so you can easily install the Add-on. It connects your Home Assistant Instance via a secure tunnel to a domain or subdomain at Cloudflare. By doing that, you can expose your Home Assistant to the Internet without opening ports in your router. Additionally, you can utilise Cloudflare Teams to further secure your Home Assistant connection.

What’s next?

I invite all of you to test the add-on. Since this is my first add-on, any feedback is very much appreciated. My plan is to bring this add-on to the Add-On Community Repository at some point. I tried following the best-practices from the example add-on as much as possible and am happy about any suggestions to improve.

Regarding additional functionality, there are a couple of things that could be included in future releases:

  • The existing tunnel can also be used to connect to Cloudflares DNS servers in a secure way. Using that, HA could be used as a DNS server in your local network, leveraging the security features of Cloudflare Teams. It might be a good idea to do that in combination with the Dnsmasq Add-On.
  • The tunnel can also be used for multiple inbound connections and decide based on the domain, which service to call. With a proper config, a simple reverse proxy in the network for other services (e.g. DiskStation, Router configuration) could be realised. (done)
  • I am currently testing to use HomeAssistant as an application in Cloudflare Teams behind an additional layer of Authentication. So far, Google is not working, but GitHub is. I am investigating how this is working out and expanding the documentation accordingly.

I do have two one issues that I would love to address:

  1. I have included a bool var in the config to reset the add-on and delete all the config files. I would be happy to get a second opinion on that approach and try other options (see issue on GitHub). (fixed)
    1. When initially setting up Cloudflared, you have to authenticate the add-on. To do that, the add-on prints a URL in the Log section that you have to open. I would love to use that URL and automatically open a new website tab or mobile browser on the app, if this is possible at all (see issue on GitHub).(this is unfortunately not possible in HA right now, still I think the set-up is fine the way it is right now).

Overall, everyone please feel free to reach out to me in this thread, via a GitHub Issue here or directly. I am happy to continue the development on this.

Best
Tobias

77 Likes

Looks really good!

I mainly have it as experimental so people go easy if there are bugs :smiley:

1 Like

How will cloudflare handle when you have addons running that also must accessed from outside.
They all have different ports. Now i have for all those addons subdomains and in NPM i redirect those subdomains to the location and port of the addon.

EDIT:
I read some information now. Only specific ports are able to use. So what i think now is use port 80 and 443 and then add the cloudflare domain into NPM so it will redirect correctly?

1 Like

Thanks for your question @poudenes. Generally, you can route as many connections through the tunnel as you like. Nevertheless, currently the add-on is only forwarding traffic from one domain that you specify in the config to your homeassistant instance.
I am working on including the npm add-on as well (in this branch), so you can set a config flag which will enable you to not only make homeassistant available but any other proxy host from NPM. You would only need to create CNAME records in Cloudflare for all the subdomains you want to use to the cloudflare tunnel (or to your “main” subdomain that is used and automatically created for the home assistant connection).

I will let you know once this is available.

1 Like

Take a look at GitHub - sabeechen/hassio-google-drive-backup: Automatically create and sync Home Assistant backups into Google Drive, they have a web UI that allows authenticating Google Drive. Maybe a similar approach could be used here?
Ideally, there should be a way to open a specific URL from the addon, but for now, maybe this will work.

1 Like

thanks a lot @Misiu. Looking at that solution, they are using an always-running frontend for setting up the backup. To do that, you also have to specify the URL of the add-on when defining it in the add-on config. Since I do not have any sort of frontend and this URL only needs to be called initially to authenticate, I do not think this is a better approach then currently where you have to manually copy the URL from the logs.
Nevertheless, your input is very much appreciated and maybe we’ll find a way to produce someting like a pop-up or a new tab.

1 Like

@poudenes I just release the new version 0.1.6. This includes the described flag as a config option.
Please have a look at the documentation for further information. Since I am not using NPM and only tested some simple websites via multiple docker containers, I would be happy to get feedback from you on the set-up and the performance.

What i will do is build a test HA on a different RPi4 and add some add-ons.
Then i will use one of my domains to change name servers to Cloudflare and then do some tests.

I have a busy period so it wont be in a day that you get some feedback :slight_smile:

1 Like

Test this add-on on a a test RPi with HAOS 6.6
Have installed Nextcloud, Joplin Server, Bitwarden and Nginx Proxy Manager.

All addons are accessible from outside now without opening ports in router!

Even the HA App (iOS and Android) is working!!!

Great job!

2 Likes

@brenner-tobias Thank you! I set this up last night, something recently happened and I was getting error 522 on all my cloudflare CNAME’s back through my internal network. I implemented your add-on (and replaced my NGINX VM with NPM add-on). Things are working great.

…except I am struggling on how to handle clicking on the link to open NPM (port 81), it eventually times out. Not sure where the breakdown is happening. I read up above about creating a subdomain and then going that route…doable but want to understand what might be happening. Any suggestions?

I am happy the add-on works for you. A couple of things regarding the NPM UI.
The Add-On is not using Ingress (see here and here). That means, that the “Open Web UI” button is basically taking your current connection URL, strips the ending of it, adds the port of the UI (in our case 81) and opens a new tab with that URL.
Now if you are connected via your external URL (e.g. home.example.com), this means that the link it is opening is “home.example.com:81”. This external URL will then hit the Cloudflared Proxy, which does not forward the port 81 to your home assistant instance, since it only forwards certain ports. This is a good thing: We do not want any other port to be exposed to the internet then the ones we defined. So the link does not work.
What does work is visiting NPM locally. You can do this by either connecting to HA using the local link in your network (e.g. http://192.168.1.10:8123) and clicking on the UI Button of NPM, or directly changing your HA link to the correct one to NPM (in our case http://192.168.1.10:81).
Now from my perspective this behaviour is fine, since you do not really want to expose the NPM UI to the internet in the first place and do not have to visit it that often.
Nevertheless, if you do, there is the possibility that you also mentioned to create a subdomain (e.g. npm.example.com) in Cloudflare and then add a forward in your NPM to your local NPM address, following the documentation of the add-on. This would still mean that the UI Button in the Add-On would not work, but you would have another subdomain that is externally available to open the NPM UI.
Additionally, we could theoretically fork the NPM add-on and change the way it behaves, moving from a separate website to Ingress to open NPM in HomeAssistant directly (the way the file editor and some other add-ons are working already). Probably @frenck had his reasons for not doing that and again I do not really see the need to be able to open NPM from everywhere. I might look into that though just because I have never done an ingress config at an add-on.

Let me know if you managed to access NPM and what you think of my thoughts!

Best
Tobias

1 Like

Thank you for the quick response. Now I understand, you make a great point on “how often you need to use NPM from external”. I went ahead and created a sub-domain and used the iframe_panel to create a link to make it easier to get to the UI just so I can find it when I need it. Much appreciated and look for any new creations you are working on.

Might need to fork NPM just to get a black theme. :slight_smile:

1 Like

That’s great to hear, glad everything works for you. I do recommend though to reconsider exposing the NPM UI directly with a subdomain. In your set-up, the only thing, that stands between an intruder and your complete internal reverse proxy settings is a very simple login page, which is not up-to-date and does not include 2FA.
If you really need to keep it and see no other way at all, I would at least add it as a Cloudflare Access Application (see here for a simple tutorial). This is also free and that way, at least you do have another layer of security by using your GitHub or Google login for example, both incl. 2FA.

Let me know if you have any other problems or if there is anything else I can help you with.

Edit: You could also change the iframe Panel to the internal URL. That way, it would always work if you are in your internal network but not, if you are not. If this would be sufficient, there would be no need for external access.

1 Like

If you do not own a domain name, read here how to get one for free:

2 Likes

I have my HA domain. :slight_smile:

Why I can not add domain in cloudflare?

Error:

Did you enter this in Cloudflare page?

Yes I did.

Then I think its something with Cloudflare and not the add-on.

Definitely an issue with Cloudflare+Freenom, so not related to the add-on (but potentially to my article on how to get a domain for free to use with the add-on…).
@lpt2007 I will send you a PM so we can try to figure out what’s happening there.