mirror of
https://github.com/aljazceru/addons.git
synced 2025-12-17 05:04: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]
|
||||
|
||||
## About
|
||||
|
||||
Setting up Letsencrypt allows you to use validated certificates for your webpages and webinterfaces.
|
||||
Setting up Letsencrypt allows you to use validated certificates for your webpages and web-interfaces.
|
||||
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.
|
||||
|
||||
## 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
|
||||
[forum]: https://community.home-assistant.io
|
||||
[issue]: https://github.com/home-assistant/hassio-addons/issues
|
||||
|
||||
Reference in New Issue
Block a user