diff --git a/README.md b/README.md index 364be1b..fee06b7 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ https://github.com/brenner-tobias/ha-addons ### ✓ [Cloudflared][addon-cloudflared] -![Latest Version][cloudflared-version-shield] +![Latest Version][cloudflared-release-shield] ![Supports armhf Architecture][cloudflared-armhf-shield] ![Supports armv7 Architecture][cloudflared-armv7-shield] ![Supports aarch64 Architecture][cloudflared-aarch64-shield] @@ -67,7 +67,7 @@ SOFTWARE. [cloudflared-armhf-shield]: https://img.shields.io/badge/armhf-yes-green.svg [cloudflared-armv7-shield]: https://img.shields.io/badge/armv7-yes-green.svg [cloudflared-i386-shield]: https://img.shields.io/badge/i386-yes-green.svg -[cloudflared-version-shield]: https://img.shields.io/badge/version-v0.1.0-blue.svg +[cloudflared-release-shield]: https://img.shields.io/github/release/brenner-tobias/addon-cloudflared [license-shield]: https://img.shields.io/github/license/brenner-tobias/ha-addons [maintenance-shield]: https://img.shields.io/maintenance/yes/2021.svg [project-stage-shield]: https://img.shields.io/badge/project%20stage-experimental-yellow.svg diff --git a/cloudflared/CHANGELOG.md b/cloudflared/CHANGELOG.md new file mode 100644 index 0000000..e69de29 diff --git a/cloudflared/DOCS.md b/cloudflared/DOCS.md new file mode 100644 index 0000000..438aabf --- /dev/null +++ b/cloudflared/DOCS.md @@ -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 diff --git a/cloudflared/README.md b/cloudflared/README.md new file mode 100644 index 0000000..340e87d --- /dev/null +++ b/cloudflared/README.md @@ -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 diff --git a/cloudflared/config.yaml b/cloudflared/config.yaml new file mode 100644 index 0000000..82a4f6c --- /dev/null +++ b/cloudflared/config.yaml @@ -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)? diff --git a/cloudflared/icon.png b/cloudflared/icon.png new file mode 100644 index 0000000..f5b0f7e Binary files /dev/null and b/cloudflared/icon.png differ diff --git a/cloudflared/logo.png b/cloudflared/logo.png new file mode 100644 index 0000000..8d5fa7b Binary files /dev/null and b/cloudflared/logo.png differ