hassio-addons/addon-wireguard
1
0
Fork 0
mirror of https://github.com/hassio-addons/addon-wireguard.git synced 2025-05-05 11:21:26 +00:00
Code Issues Projects Releases Packages Wiki Activity

📚 Improve wording, adding a bit more security perspective

Browse source
This commit is contained in:
Franck Nijhof 2019-08-30 12:54:05 +02:00
parent c4f17fee94
commit a349b8da3f
No known key found for this signature in database
GPG key ID: D62583BA8AB11CA3
1 changed files with 50 additions and 36 deletions
Download patch file Download diff file Expand all files Collapse all files

86
README.md
View file

@ -43,26 +43,27 @@ in the industry.
## Installation ## Installation
The installation of this add-on is pretty straightforward and not different in WireGuard is pretty simple, however, can be quite complex for user that isn't
comparison to installing any other Hass.io add-on. familiar with all terminology used. The add-on takes care of a lot of things
for you (if you want).
This is an installation manual & quick start: Follow the following steps for installation & a quick start:
1. [Add our Hass.io add-ons repository][repository] to your Hass.io instance. 1. [Add our Hass.io add-ons repository][repository] to your Hass.io instance.
1. Install the "WireGuard" add-on. 2. Install the "WireGuard" add-on.
1. Set the `host` configuration option to your Hass.io (external) address, 3. Set the `host` configuration option to your Hass.io (external) address,
e.g., `myhome.duckdns.org`. e.g., `myhome.duckdns.org`.
1. Change the name of the peer to something useful, e.g., `myphone`. 4. Change the name of the peer to something useful, e.g., `myphone`.
1. Save the configuration. 5. Save the configuration.
1. Start the "WireGuard" add-on 6. Start the "WireGuard" add-on
1. Check the logs of the "WireGuard" add-on to see if everything went well. 7. Check the logs of the "WireGuard" add-on to see if everything went well.
1. Forward port `51820` (UDP!) in your router to your Hass.io IP. 8. Forward port `51820` (UDP!) in your router to your Hass.io IP.
1. Download/Open the file `/ssl/wireguard/myphone/qrcode.png` stored on your 9. Download/Open the file `/ssl/wireguard/myphone/qrcode.png` stored on your
Hass.io machine, e.g., using Samba, Visual Studio Code or the Configurator Hass.io machine, e.g., using Samba, Visual Studio Code or the Configurator
add-on. add-on.
1. Install the WireGuard app on your phone. 10. Install the WireGuard app on your phone.
1. Add a new WireGuard connection to your phone, by scanning the QR code. 11. Add a new WireGuard connection to your phone, by scanning the QR code.
1. Connect! 12. Connect!
**NOTE**: Do not add this repository to Hass.io, please use: **NOTE**: Do not add this repository to Hass.io, please use:
`https://github.com/hassio-addons/repository`. `https://github.com/hassio-addons/repository`.
@ -70,10 +71,10 @@ This is an installation manual & quick start:
## Configuration ## Configuration
Now, for starters, don't get scared by the number of options and difficult Now, for starters, don't get scared by the number of options and difficult
terms this add-on provides. WireGuard is a complex machine, but the terms this add-on provides. WireGuard can be a complex piece of software,
add-on only has a few, simple, required settings. All the rest is handled by but the add-on only has a few, simple, required settings. All the rest is
the add-on. However, If you would like to set up a more complex configuration, handled by the add-on. However, If you would like to set up a more complex
the add-on would allow that to. configuration, the add-on would allow that to.
If you are familiar with WireGuard, please note the following: If you are familiar with WireGuard, please note the following:
The configuration of WireGuard looks very similar to all terms used in the The configuration of WireGuard looks very similar to all terms used in the
@ -109,6 +110,7 @@ A little more extensive example add-on configuration:
} }
{ {
"name": "ninja", "name": "ninja",
"public_key": "QNLXV8lrsPnKOd011DO8g5DWyad6iHJDSVOD6yOqjiE=",
"addresses": [ "addresses": [
"10.10.10.3" "10.10.10.3"
], ],
@ -136,11 +138,11 @@ work.
### Option: `server.addresses` ### Option: `server.addresses`
A list of IP (ipv4 or ipv6) addresses (optionally with CIDR masks) to be A list of IP (IPv4 or IPv6) addresses (optionally with CIDR masks) to be
assigned to the server/add-on interface. assigned to the server/add-on interface.
It is strongly advised to create/use a separate IP address space from your It is strongly advised to create/use a separate IP address space from your
home network, e.g., if your home network uses `192.168.1.x` then DON'T use home network, e.g., if your home network uses `192.168.1.x` then DO NOT use
that for the add-on. that for the add-on.
### Option: `server.dns` _(optional)_ ### Option: `server.dns` _(optional)_
@ -168,12 +170,13 @@ from a private key. This option supports the use of `!secret`.
If you don't supply one, the add-on will calculate one based on the private If you don't supply one, the add-on will calculate one based on the private
key that was supplied via the `server.private_key` or, in case no private key key that was supplied via the `server.private_key` or, in case no private key
was supplied, calculated it from the generated private key. was supplied, calculate it from the generated private key.
### Option: `server.fwmark` _(optional)_ ### Option: `server.fwmark` _(optional)_
A 32-bit fwmark for outgoing packets. A 32-bit fwmark for outgoing packets. May be specified in hexadecimal by
May be specified in hexadecimal by prepending "0x". prepending "0x". If you don't know what this is, then you probably don't
need it.
### Option: `server.table` _(optional)_ ### Option: `server.table` _(optional)_
@ -183,13 +186,11 @@ adds routes to the default table and enables special handling of default routes.
### Option: `server.pre_up` _(optional)_ ### Option: `server.pre_up` _(optional)_
Allows you to run commands before WireGuard is started. This is useful Allows you to run commands before WireGuard is started.
for modifying things like routing.
### Option: `server.pre_down` _(optional)_ ### Option: `server.pre_down` _(optional)_
Allows you to run commands before WireGuard is stopped. This is useful Allows you to run commands before WireGuard is stopped.
for modifying things like routing.
### Option: `server.post_up` _(optional)_ ### Option: `server.post_up` _(optional)_
@ -221,7 +222,7 @@ By default it executes the following:
iptables -D FORWARD -o %i -j ACCEPT; iptables -D FORWARD -o %i -j ACCEPT;
iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE` iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE`
### Option: `server.mtu` ### Option: `server.mtu` _(optional)_
The MTU is automatically determined from the endpoint addresses or the The MTU is automatically determined from the endpoint addresses or the
system default route, which is usually a sane choice. system default route, which is usually a sane choice.
@ -258,7 +259,12 @@ generate client configurations, it can be helpful.
If no private key and no public key is provided, the add-on will generate one If no private key and no public key is provided, the add-on will generate one
for you and store it in: `/ssl/wireguard/<peer.name>/`. for you and store it in: `/ssl/wireguard/<peer.name>/`.
### Option: `peers.public_key` _(optional)_ **Private keys, in general, should only be known by client, while this add-on
supports setting or generating one for your client is helpful and easy, it
isn't the best security practice. The best practice is to provide just the
`peers.public_key` option below, the add-on will honor that.**
### Option: `peers.public_key` _(optional, but recommended!)_
Allows you to provide your own a base64 public key calculated by `wg pubkey` Allows you to provide your own a base64 public key calculated by `wg pubkey`
from a private key. This option supports the use of `!secret`. from a private key. This option supports the use of `!secret`.
@ -267,6 +273,11 @@ If you don't supply one, the add-on will calculate one based on the private
key that was supplied via the `peer.private_key` or, in case no private key key that was supplied via the `peer.private_key` or, in case no private key
was supplied, calculated it from the generated private key for this peer. was supplied, calculated it from the generated private key for this peer.
**While this add-on can generate public/private keypairs, from best security
practice perspective, it is strongly advised to manually provide a public key
for each of your peers. In that case, the add-on will not generate or configure
a private key by itself.**
### Option: `peers.allowed_ips` _(optional)_ ### Option: `peers.allowed_ips` _(optional)_
**This configuration only valid for the add-on/server end and does not **This configuration only valid for the add-on/server end and does not
@ -307,10 +318,11 @@ For example, if the interface very rarely sends traffic, but it might at
anytime receive traffic from a peer, and it is behind NAT, the interface might anytime receive traffic from a peer, and it is behind NAT, the interface might
benefit from having a persistent keepalive interval of 25 seconds. benefit from having a persistent keepalive interval of 25 seconds.
If set to 0 or "off", this option is disabled. By default or when unspecified, this option is set to 25 seconds. This is
different from the WireGuard default, since the use case for this add-on is
most likely to be installed in home setups behind a NAT.
By default or when unspecified, this option is off. If set to "off", this option is disabled.
Most users will not need this.
### Option: `peers.endpoint` _(optional)_ ### Option: `peers.endpoint` _(optional)_
@ -332,8 +344,9 @@ public-key cryptography, for post-quantum resistance.
**This configuration only valid for the peer end/client configuration and does **This configuration only valid for the peer end/client configuration and does
not affect the server/add-on!** not affect the server/add-on!**
A 32-bit fwmark for outgoing packets. A 32-bit fwmark for outgoing packets. May be specified in hexadecimal by
May be specified in hexadecimal by prepending "0x". prepending "0x". If you don't know what this is, then you probably don't
need it.
### Option: `log_level` _(optional)_ ### Option: `log_level` _(optional)_
@ -363,7 +376,7 @@ add-on configuration. The add-on additionally generates an image for each
client containing a QR code, to allow a quick an easy set up on, e.g., your client containing a QR code, to allow a quick an easy set up on, e.g., your
mobile phone. mobile phone.
## Running this add-on on a Generic/Debian/Ubuntu-based Hass.io ## Using on a Generic Linux/Debian/Ubuntu-based Hass.io system
The HassOS operating system for Hass.io by default has installed WireGuard The HassOS operating system for Hass.io by default has installed WireGuard
support in its Linux kernel. However, if you run Hass.io on a generic Linux support in its Linux kernel. However, if you run Hass.io on a generic Linux
@ -437,7 +450,8 @@ sudo sysctl -p /etc/sysctl.conf
The WireGuard add-on can be backed up using Hass.io snapshots. There is one The WireGuard add-on can be backed up using Hass.io snapshots. There is one
caveat to take into account: A partial snapshot of the add-on DOES NOT contain caveat to take into account: A partial snapshot of the add-on DOES NOT contain
the generated client configurations, including their public/private keys. the generated client configurations, including their public/private keys
(if those keys are generated by the add-on).
Client configurations are stored in the `/ssl/wireguard` folder. If you Client configurations are stored in the `/ssl/wireguard` folder. If you
use partial snapshots, please be sure to backup both the `ssl` folder and the use partial snapshots, please be sure to backup both the `ssl` folder and the