Added Cloudflared Add-On

2021-11-28 14:16:00 +01:00
parent 6c1ad366ae
commit 3da60c72cc
7 changed files with 239 additions and 2 deletions
@@ -0,0 +1,129 @@
+# Home Assistant Add-on: Cloudflared
+
+Cloudflared connects your Home Assistant Instance via a secure tunnel to a domain
+or subdomain at Cloudflare. Doing that, you can expose your Home Assitant to the
+Internet without opening ports in your router. Additionally, you can utilize
+Cloudflare Teams, their Zero Trust platform to further secure your Home Assistant
+connection.
+
+**To use this add-on you have to own a domain name (e.g. example.com) and use the
+DNS servers of cloudflare.**
+
+## Installation
+
+The installation of this add-on is pretty straightforward but requires some prerequisites
+and a manual step at the first set-up:
+
+1. (Optional if you don't yet have a working Cloudflare set-up):
+   Get a domain name and set-up Cloudflare. See section
+   [Domain Name and Cloudlfare Set-Up](#domain-name-and-cloudlfare-set-up) for details.
+1. Set the "external_hostname" add-on option with your domain name or a subdomain
+   that you want to use to access Home Assistant.
+1. (Optional) Change the "internal_ha_port" add-on option with the internal Port
+   to reach Home Assistant in your network (default: 8123).
+1. (Optional) Change the "tunnel_name" add-on option (default: homeassistant).
+1. **Make sure that there is no DNS entry with your desired external hostname and
+   no existing tunnel with your desired tunnel name at Cloudflare**.
+1. Start the "Cloudflare" add-on.
+1. Check the logs of the "Cloudflare" add-on and **follow the instruction to authenticate
+   at cloudflare**.
+   You need to copy a URL from the logs and visit it to authenticate.
+1. A tunnel and a DNS entry will be created and show up in your cloudflare DNS /
+   Teams dashboard.
+
+## Configuration
+
+**Note**: _Remember to restart the add-on when the configuration is changed._
+
+Example add-on configuration:
+
+```yaml
+internal_ha_port: "8123"
+external_hostname: "ha.example.com"
+tunnel_name: homeassistant
+```
+
+**Note**: _This is just an example, don't copy and paste it! Create your own!_
+
+### Configuration.yaml
+
+Since HomeAssistant blocks requests via proxies or reverse proxies, you have to tell
+your instance to allow requests from the Cloudflared Add-On. The add-on runs locally,
+so HA hasto trust the docker network. In order to do so, add the following lines
+to your /config/configuration.yaml (if you need assistance changing the config,
+please follow the [Advanced Configuration Tutorial][advancedconfiguration]):
+
+```yaml
+http:
+  use_x_forwarded_for: true
+  trusted_proxies:
+    - 172.30.33.0/24
+```
+
+### Option: `log_level`
+
+The `log_level` option controls the level of log output by the addon and can
+be changed to be more or less verbose, which might be useful when you are
+dealing with an unknown issue. Possible values are:
+
+- `trace`: Show every detail, like all called internal functions.
+- `debug`: Shows detailed debug information.
+- `info`: Normal (usually) interesting events.
+- `warning`: Exceptional occurrences that are not errors.
+- `error`: Runtime errors that do not require immediate action.
+- `fatal`: Something went terribly wrong. Add-on becomes unusable.
+
+Please note that each level automatically includes log messages from a
+more severe level, e.g., `debug` also shows `info` messages. By default,
+the `log_level` is set to `info`, which is the recommended setting unless
+you are troubleshooting.
+
+## Domain Name and Cloudlfare Set-Up
+
+To use this plugin, you need a domain name that is using Cloudflare for its
+DNS entries.
+
+### Domain Name
+
+If you do not already have a domain name, get one. In case you dont want
+to pay for a domain name, you can look for a free domain name at
+[freenom][freenom].
+
+### Cloudflare
+
+Create a free Cloudflare Account at [cloudflare.com][cloudflare] and follow
+the tutorial [Getting started with Cloudflare][cloudflaretutorial].
+
+## Authors & contributors
+
+The original setup of this repository is by [Tobias Brenner][tobias].
+
+## License
+
+MIT License
+
+Copyright (c) 2021 Tobias Brenner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+[advancedconfiguration]: https://www.home-assistant.io/getting-started/configuration/
+[cloudflare]: https://www.cloudflare.com/
+[cloudflaretutorial]: https://support.cloudflare.com/hc/en-us/articles/360027989951-Getting-Started-with-Cloudflare
+[freenom]: https://freenom.com
+[tobias]: https://github.com/brenner-tobias
@@ -0,0 +1,82 @@
+# Home Assistant Add-on: Cloudflared
+
+[![GitHub Release][releases-shield]][releases]
+![Project Stage][project-stage-shield]
+[![License][license-shield]](LICENSE.md)
+
+![Supports aarch64 Architecture][aarch64-shield]
+![Supports amd64 Architecture][amd64-shield]
+![Supports armhf Architecture][armhf-shield]
+![Supports armv7 Architecture][armv7-shield]
+![Supports i386 Architecture][i386-shield]
+
+[![Github Actions][github-actions-shield]][github-actions]
+![Project Maintenance][maintenance-shield]
+
+Connect remotely to your Home Assistant instance without opening any ports using
+Cloudflared.
+
+## About
+
+Cloudflared connects your Home Assistant Instance via a secure tunnel to a domain
+or subdomain at Cloudflare. Doing that, you can expose your Home Assitant to the
+Internet without opening ports in your router. Additionally, you can utilize
+Cloudflare Teams, their Zero Trust platform to further secure your Home Assistant
+connection.
+
+**To use this add-on you have to own a domain name (e.g. example.com) and use the
+DNS servers of cloudflare. If you do not have a domain name, you can register a
+free one at [freenom][freenom]**
+
+[:books: Read the full add-on documentation][docs]
+
+## Support
+
+Got questions?
+
+Feel free to [open an issue here][issue] on GitHub.
+
+## Author
+
+[Tobias Brenner][tobias]
+
+## License
+
+MIT License
+
+Copyright (c) 2021 Tobias Brenner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+[aarch64-shield]: https://img.shields.io/badge/aarch64-yes-green.svg
+[amd64-shield]: https://img.shields.io/badge/amd64-yes-green.svg
+[armhf-shield]: https://img.shields.io/badge/armhf-yes-green.svg
+[armv7-shield]: https://img.shields.io/badge/armv7-yes-green.svg
+[docs]: cloudflared/DOCS.md
+[freenom]: https://freenom.com
+[github-actions-shield]: https://github.com/brenner-tobias/addon-cloudflared/workflows/CI/badge.svg
+[github-actions]: https://github.com/brenner-tobias/addon-cloudflared//actions
+[i386-shield]: https://img.shields.io/badge/i386-yes-green.svg
+[issue]: https://github.com/brenner-tobias/addon-cloudflared/issues
+[license-shield]: https://img.shields.io/github/license/brenner-tobias/addon-cloudflared
+[maintenance-shield]: https://img.shields.io/maintenance/yes/2021.svg
+[project-stage-shield]: https://img.shields.io/badge/project%20stage-experimental-yellow.svg
+[releases-shield]: https://img.shields.io/github/release/brenner-tobias/addon-cloudflared
+[releases]: https://github.com/brenner-tobias/addon-cloudflared/releases
+[tobias]: https://github.com/brenner-tobias
@@ -0,0 +1,26 @@
+---
+name: Cloudflared
+version: dev
+slug: cloudflared
+description: >
+  Add-On to use a Cloudflared tunnel (formerly Argo Tunnel)
+  to remotely connect to your Home Assistant without opening any ports
+url: "https://github.com/brenner-tobias/addon-cloudflared/"
+image: ghcr.io/brenner-tobias/cloudflared/{arch}
+startup: services
+init: false
+arch:
+  - aarch64
+  - amd64
+  - armhf
+  - armv7
+  - i386
+options:
+  external_hostname: ""
+  internal_ha_port: "8123"
+  tunnel_name: homeassistant
+schema:
+  external_hostname: str
+  internal_ha_port: port
+  tunnel_name: str
+  log_level: list(trace|debug|info|notice|warning|error|fatal)?