mirror of
https://github.com/aljazceru/addons.git
synced 2025-12-17 13:14:21 +01:00
letsencrypt: Split documentation (#1309)
This commit is contained in:
Franck Nijhof
203
letsencrypt/DOCS.md
Normal file
203
letsencrypt/DOCS.md
Normal file
@@ -0,0 +1,203 @@
|
|||||||
|
# Home Assistant Add-on: Letsencrypt
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
Follow these steps to get the add-on installed on your system:
|
||||||
|
|
||||||
|
1. Navigate in your Home Assistant frontend to **Supervisor** -> **Add-on Store**.
|
||||||
|
2. Find the "letsencrypt" add-on and click it.
|
||||||
|
3. Click on the "INSTALL" button.
|
||||||
|
|
||||||
|
## How to use
|
||||||
|
|
||||||
|
To use this add-on, you have two options on how to get your certificate:
|
||||||
|
|
||||||
|
### 1. http challenge
|
||||||
|
|
||||||
|
- Requires Port 80 to be available from the internet and your domain assigned to the externally assigned IP address
|
||||||
|
- Doesnt allow wildcard certificates (*.yourdomain.com).
|
||||||
|
|
||||||
|
### 2. dns challenge
|
||||||
|
|
||||||
|
- Requires you to use one of the supported DNS providers (See "Supported DNS providers" below)
|
||||||
|
- Allows to request wildcard certificates (*.yourdomain.com)
|
||||||
|
- Doesn’t need you to open a port to your Home Assistant host on your router.
|
||||||
|
|
||||||
|
### You always need to provide the following entries within the configuration
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
email: your@email.com
|
||||||
|
domains:
|
||||||
|
# use "*.yourdomain.com" for wildcard certificates.
|
||||||
|
- yourdomain.com
|
||||||
|
challenge: http OR dns
|
||||||
|
```
|
||||||
|
|
||||||
|
IF you choose "dns" as "challenge", you will also need to fill:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
# Add the dnsprovider of your choice from the list of "Supported DNS providers" below
|
||||||
|
dnsprovider: ""
|
||||||
|
```
|
||||||
|
|
||||||
|
In addition add the fields according to the credentials required by your dns provider:
|
||||||
|
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
propagation_seconds: 60
|
||||||
|
cloudflare_email: ''
|
||||||
|
cloudflare_api_key: ''
|
||||||
|
cloudflare_api_token: ''
|
||||||
|
cloudxns_api_key: ''
|
||||||
|
cloudxns_secret_key: ''
|
||||||
|
digitalocean_token: ''
|
||||||
|
dnsimple_token: ''
|
||||||
|
dnsmadeeasy_api_key: ''
|
||||||
|
dnsmadeeasy_secret_key: ''
|
||||||
|
google_creds: ''
|
||||||
|
gehirn_api_token: ''
|
||||||
|
gehirn_api_secret: ''
|
||||||
|
linode_key: ''
|
||||||
|
linode_version: ''
|
||||||
|
luadns_email: ''
|
||||||
|
luadns_token: ''
|
||||||
|
nsone_api_key: ''
|
||||||
|
ovh_endpoint: ''
|
||||||
|
ovh_application_key: ''
|
||||||
|
ovh_application_secret: ''
|
||||||
|
ovh_consumer_key: ''
|
||||||
|
rfc2136_server: ''
|
||||||
|
rfc2136_port: ''
|
||||||
|
rfc2136_name: ''
|
||||||
|
rfc2136_secret: ''
|
||||||
|
rfc2136_algorithm: ''
|
||||||
|
aws_access_key_id: ''
|
||||||
|
aws_secret_access_key: ''
|
||||||
|
sakuracloud_api_token: ''
|
||||||
|
sakuracloud_api_secret: ''
|
||||||
|
netcup_customer_id: ''
|
||||||
|
netcup_api_key: ''
|
||||||
|
netcup_api_password: ''
|
||||||
|
```
|
||||||
|
|
||||||
|
## Example Configurations
|
||||||
|
|
||||||
|
### http challenge
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
email: hello@home-assistant.io
|
||||||
|
domains:
|
||||||
|
- home-assistant.io
|
||||||
|
certfile: fullchain.pem
|
||||||
|
keyfile: privkey.pem
|
||||||
|
challenge: http
|
||||||
|
dns: {}
|
||||||
|
```
|
||||||
|
|
||||||
|
### dns challenge
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
email: hello@home-assistant.io
|
||||||
|
domains:
|
||||||
|
- home-assistant.io
|
||||||
|
certfile: fullchain.pem
|
||||||
|
keyfile: privkey.pem
|
||||||
|
challenge: dns
|
||||||
|
dns:
|
||||||
|
provider: dns-cloudflare
|
||||||
|
cloudflare_email: cf@home-assistant.io
|
||||||
|
cloudflare_api_key: 31242lk3j4ljlfdwsjf0
|
||||||
|
```
|
||||||
|
|
||||||
|
### google dns challenge
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
email: hello@home-assistant.io
|
||||||
|
domains:
|
||||||
|
- home-assistant.io
|
||||||
|
certfile: fullchain.pem
|
||||||
|
keyfile: privkey.pem
|
||||||
|
challenge: dns
|
||||||
|
dns:
|
||||||
|
provider: dns-google
|
||||||
|
google_creds: google.json
|
||||||
|
```
|
||||||
|
|
||||||
|
Please copy your credentials file "google.json" into the "share" shared folder on the Home Assistant host before starting the service.
|
||||||
|
|
||||||
|
One way is to use the "Samba" add on to make the folder available via network or SSH Add-on.
|
||||||
|
|
||||||
|
The credential file can be created and downloaded when creating the service user within the Google cloud.
|
||||||
|
You can find additional information in regards to the required permissions in the "credentials" section here:
|
||||||
|
|
||||||
|
<https://github.com/certbot/certbot/blob/master/certbot-dns-google/certbot_dns_google/__init__.py>
|
||||||
|
|
||||||
|
### CloudFlare
|
||||||
|
|
||||||
|
Previously, Cloudflare’s “Global API Key” was used for authentication, however this key can access the entire Cloudflare API for all domains in your account, meaning it could cause a lot of damage if leaked.
|
||||||
|
|
||||||
|
Cloudflare’s newer API Tokens can be restricted to specific domains and operations, and are therefore now the recommended authentication option.
|
||||||
|
|
||||||
|
However, due to some shortcomings in Cloudflare’s implementation of Tokens, Tokens created for Certbot currently require `Zone:Zone:Read` and `Zone:DNS:Edit` permissions for all zones in your account.
|
||||||
|
|
||||||
|
Example credentials file using restricted API Token (recommended):
|
||||||
|
```yaml
|
||||||
|
dns:
|
||||||
|
provider: dns-cloudflare
|
||||||
|
cloudflare_api_token: 0123456789abcdef0123456789abcdef01234
|
||||||
|
```
|
||||||
|
|
||||||
|
Example credentials file using Global API Key (not recommended):
|
||||||
|
```yaml
|
||||||
|
dns:
|
||||||
|
provider: dns-cloudflare
|
||||||
|
cloudflare_email: cloudflare@example.com
|
||||||
|
cloudflare_api_key: 0123456789abcdef0123456789abcdef01234
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
## Certificate files
|
||||||
|
|
||||||
|
The certificate files will be available within the "ssl" share after successful request of the certificates.
|
||||||
|
|
||||||
|
By default other addons are referring to the correct path of the certificates.
|
||||||
|
You can in addition find the files via the "samba" addon within the "ssl" share.
|
||||||
|
|
||||||
|
## Supported DNS providers
|
||||||
|
|
||||||
|
```txt
|
||||||
|
dns-cloudflare
|
||||||
|
dns-cloudxns
|
||||||
|
dns-digitalocean
|
||||||
|
dns-dnsimple
|
||||||
|
dns-dnsmadeeasy
|
||||||
|
dns-gehirn
|
||||||
|
dns-google
|
||||||
|
dns-linode
|
||||||
|
dns-luadns
|
||||||
|
dns-nsone
|
||||||
|
dns-ovh
|
||||||
|
dns-rfc2136
|
||||||
|
dns-route53
|
||||||
|
dns-sakuracloud
|
||||||
|
dns-netcup
|
||||||
|
```
|
||||||
|
|
||||||
|
## Support
|
||||||
|
|
||||||
|
Got questions?
|
||||||
|
|
||||||
|
You have several options to get them answered:
|
||||||
|
|
||||||
|
- The [Home Assistant Discord Chat Server][discord].
|
||||||
|
- The Home Assistant [Community Forum][forum].
|
||||||
|
- Join the [Reddit subreddit][reddit] in [/r/homeassistant][reddit]
|
||||||
|
- Check out certbots page [certbot].
|
||||||
|
|
||||||
|
In case you've found a bug, please [open an issue on our GitHub][issue].
|
||||||
|
|
||||||
|
[discord]: https://discord.gg/c5DvZ4e
|
||||||
|
[forum]: https://community.home-assistant.io
|
||||||
|
[issue]: https://github.com/home-assistant/hassio-addons/issues
|
||||||
|
[certbot]: https://certbot.eff.org
|
||||||
|
[reddit]: https://reddit.com/r/homeassistant
|
||||||
@@ -4,214 +4,11 @@ Let's Encrypt is a certificate authority that provides free X.509 certificates f
|
|||||||
|
|
||||||
![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]
|
![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]
|
||||||
|
|
||||||
## About
|
Setting up Letsencrypt allows you to use validated certificates for your webpages and web-interfaces.
|
||||||
|
|
||||||
Setting up Letsencrypt allows you to use validated certificates for your webpages and webinterfaces.
|
|
||||||
It requires you to own the domain you are requesting the certificate for.
|
It requires you to own the domain you are requesting the certificate for.
|
||||||
|
|
||||||
The generated certificate can be used within others addons. By default the path and file for the certificates within other addons will refer to the files generated within this addon.
|
The generated certificate can be used within others addons. By default the path and file for the certificates within other addons will refer to the files generated within this addon.
|
||||||
|
|
||||||
## Installation
|
|
||||||
|
|
||||||
Follow these steps to get the add-on installed on your system:
|
|
||||||
|
|
||||||
1. Navigate in your Home Assistant frontend to **Supervisor** -> **Add-on Store**.
|
|
||||||
2. Find the "letsencrypt" add-on and click it.
|
|
||||||
3. Click on the "INSTALL" button.
|
|
||||||
|
|
||||||
## How to use
|
|
||||||
|
|
||||||
To use this add-on, you have two options on how to get your certificate:
|
|
||||||
|
|
||||||
### 1. http challenge
|
|
||||||
|
|
||||||
- Requires Port 80 to be available from the internet and your domain assigned to the externally assigned IP address
|
|
||||||
- Doesnt allow wildcard certificates (*.yourdomain.com).
|
|
||||||
|
|
||||||
### 2. dns challenge
|
|
||||||
|
|
||||||
- Requires you to use one of the supported DNS providers (See "Supported DNS providers" below)
|
|
||||||
- Allows to request wildcard certificates (*.yourdomain.com)
|
|
||||||
- Doesn’t need you to open a port to your Home Assistant host on your router.
|
|
||||||
|
|
||||||
### You always need to provide the following entries within the configuration
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
email: your@email.com
|
|
||||||
domains:
|
|
||||||
# use "*.yourdomain.com" for wildcard certificates.
|
|
||||||
- yourdomain.com
|
|
||||||
challenge: http OR dns
|
|
||||||
```
|
|
||||||
|
|
||||||
IF you choose "dns" as "challenge", you will also need to fill:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
# Add the dnsprovider of your choice from the list of "Supported DNS providers" below
|
|
||||||
dnsprovider: ""
|
|
||||||
```
|
|
||||||
|
|
||||||
In addition add the fields according to the credentials required by your dns provider:
|
|
||||||
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
propagation_seconds: 60
|
|
||||||
cloudflare_email: ''
|
|
||||||
cloudflare_api_key: ''
|
|
||||||
cloudflare_api_token: ''
|
|
||||||
cloudxns_api_key: ''
|
|
||||||
cloudxns_secret_key: ''
|
|
||||||
digitalocean_token: ''
|
|
||||||
dnsimple_token: ''
|
|
||||||
dnsmadeeasy_api_key: ''
|
|
||||||
dnsmadeeasy_secret_key: ''
|
|
||||||
google_creds: ''
|
|
||||||
gehirn_api_token: ''
|
|
||||||
gehirn_api_secret: ''
|
|
||||||
linode_key: ''
|
|
||||||
linode_version: ''
|
|
||||||
luadns_email: ''
|
|
||||||
luadns_token: ''
|
|
||||||
nsone_api_key: ''
|
|
||||||
ovh_endpoint: ''
|
|
||||||
ovh_application_key: ''
|
|
||||||
ovh_application_secret: ''
|
|
||||||
ovh_consumer_key: ''
|
|
||||||
rfc2136_server: ''
|
|
||||||
rfc2136_port: ''
|
|
||||||
rfc2136_name: ''
|
|
||||||
rfc2136_secret: ''
|
|
||||||
rfc2136_algorithm: ''
|
|
||||||
aws_access_key_id: ''
|
|
||||||
aws_secret_access_key: ''
|
|
||||||
sakuracloud_api_token: ''
|
|
||||||
sakuracloud_api_secret: ''
|
|
||||||
netcup_customer_id: ''
|
|
||||||
netcup_api_key: ''
|
|
||||||
netcup_api_password: ''
|
|
||||||
```
|
|
||||||
|
|
||||||
## Example Configurations
|
|
||||||
|
|
||||||
### http challenge
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
email: hello@home-assistant.io
|
|
||||||
domains:
|
|
||||||
- home-assistant.io
|
|
||||||
certfile: fullchain.pem
|
|
||||||
keyfile: privkey.pem
|
|
||||||
challenge: http
|
|
||||||
dns: {}
|
|
||||||
```
|
|
||||||
|
|
||||||
### dns challenge
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
email: hello@home-assistant.io
|
|
||||||
domains:
|
|
||||||
- home-assistant.io
|
|
||||||
certfile: fullchain.pem
|
|
||||||
keyfile: privkey.pem
|
|
||||||
challenge: dns
|
|
||||||
dns:
|
|
||||||
provider: dns-cloudflare
|
|
||||||
cloudflare_email: cf@home-assistant.io
|
|
||||||
cloudflare_api_key: 31242lk3j4ljlfdwsjf0
|
|
||||||
```
|
|
||||||
|
|
||||||
### google dns challenge
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
email: hello@home-assistant.io
|
|
||||||
domains:
|
|
||||||
- home-assistant.io
|
|
||||||
certfile: fullchain.pem
|
|
||||||
keyfile: privkey.pem
|
|
||||||
challenge: dns
|
|
||||||
dns:
|
|
||||||
provider: dns-google
|
|
||||||
google_creds: google.json
|
|
||||||
```
|
|
||||||
|
|
||||||
Please copy your credentials file "google.json" into the "share" shared folder on the Home Assistant host before starting the service.
|
|
||||||
|
|
||||||
One way is to use the "Samba" add on to make the folder available via network or SSH Add-on.
|
|
||||||
|
|
||||||
The credential file can be created and downloaded when creating the service user within the Google cloud.
|
|
||||||
You can find additional information in regards to the required permissions in the "credentials" section here:
|
|
||||||
|
|
||||||
<https://github.com/certbot/certbot/blob/master/certbot-dns-google/certbot_dns_google/__init__.py>
|
|
||||||
|
|
||||||
### CloudFlare
|
|
||||||
|
|
||||||
Previously, Cloudflare’s “Global API Key” was used for authentication, however this key can access the entire Cloudflare API for all domains in your account, meaning it could cause a lot of damage if leaked.
|
|
||||||
|
|
||||||
Cloudflare’s newer API Tokens can be restricted to specific domains and operations, and are therefore now the recommended authentication option.
|
|
||||||
|
|
||||||
However, due to some shortcomings in Cloudflare’s implementation of Tokens, Tokens created for Certbot currently require `Zone:Zone:Read` and `Zone:DNS:Edit` permissions for all zones in your account.
|
|
||||||
|
|
||||||
Example credentials file using restricted API Token (recommended):
|
|
||||||
```yaml
|
|
||||||
dns:
|
|
||||||
provider: dns-cloudflare
|
|
||||||
cloudflare_api_token: 0123456789abcdef0123456789abcdef01234
|
|
||||||
```
|
|
||||||
|
|
||||||
Example credentials file using Global API Key (not recommended):
|
|
||||||
```yaml
|
|
||||||
dns:
|
|
||||||
provider: dns-cloudflare
|
|
||||||
cloudflare_email: cloudflare@example.com
|
|
||||||
cloudflare_api_key: 0123456789abcdef0123456789abcdef01234
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
## Certificate files
|
|
||||||
|
|
||||||
The certificate files will be available within the "ssl" share after successful request of the certificates.
|
|
||||||
|
|
||||||
By default other addons are referring to the correct path of the certificates.
|
|
||||||
You can in addition find the files via the "samba" addon within the "ssl" share.
|
|
||||||
|
|
||||||
## Supported DNS providers
|
|
||||||
|
|
||||||
```txt
|
|
||||||
dns-cloudflare
|
|
||||||
dns-cloudxns
|
|
||||||
dns-digitalocean
|
|
||||||
dns-dnsimple
|
|
||||||
dns-dnsmadeeasy
|
|
||||||
dns-gehirn
|
|
||||||
dns-google
|
|
||||||
dns-linode
|
|
||||||
dns-luadns
|
|
||||||
dns-nsone
|
|
||||||
dns-ovh
|
|
||||||
dns-rfc2136
|
|
||||||
dns-route53
|
|
||||||
dns-sakuracloud
|
|
||||||
dns-netcup
|
|
||||||
```
|
|
||||||
|
|
||||||
## Support
|
|
||||||
|
|
||||||
Got questions?
|
|
||||||
|
|
||||||
You have several options to get them answered:
|
|
||||||
|
|
||||||
- The [Home Assistant Discord Chat Server][discord].
|
|
||||||
- The Home Assistant [Community Forum][forum].
|
|
||||||
- Join the [Reddit subreddit][reddit] in [/r/homeassistant][reddit]
|
|
||||||
- Check out certbots page [certbot].
|
|
||||||
|
|
||||||
In case you've found a bug, please [open an issue on our GitHub][issue].
|
|
||||||
|
|
||||||
[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
|
|
||||||
[i386-shield]: https://img.shields.io/badge/i386-yes-green.svg
|
|
||||||
[discord]: https://discord.gg/c5DvZ4e
|
[discord]: https://discord.gg/c5DvZ4e
|
||||||
[forum]: https://community.home-assistant.io
|
[forum]: https://community.home-assistant.io
|
||||||
[issue]: https://github.com/home-assistant/hassio-addons/issues
|
[issue]: https://github.com/home-assistant/hassio-addons/issues
|
||||||
|
|||||||
Reference in New Issue
Block a user