jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-13 20:36:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

Migration of Community Guides (#13412)

Browse Source
This commit is contained in:
Franck Nijhof 2020-05-26 19:47:24 +02:00 committed by GitHub
parent 167bec36b5
commit 22bb3daf75
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
52 changed files with 65 additions and 3441 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
source/_docs/autostart.markdown
View File

@ -1,13 +0,0 @@
---
title: "Autostart Home Assistant"
description: "Instructions on how to setup Home Assistant to launch on start."
redirect_from: /getting-started/autostart/
---
Once you get started with Home Assistant you want it to start automatically when you launch your machine. To help you get started we've compiled a few guides for different systems.
- [systemd (Linux)](/docs/autostart/systemd/)
- [Upstart (Linux)](/docs/autostart/upstart/)
- [init.d (Linux)](/docs/autostart/init.d/)
- [macOS](/docs/autostart/macos/)
- [Synology NAS](/docs/autostart/synology/)

303
source/_docs/autostart/init.d.markdown
View File

@ -1,303 +0,0 @@
---
title: "Autostart using init.d"
description: "Documentation about setting up Home Assistant as a daemon running under init.d."
redirect_from: /getting-started/autostart-init.d/
---
Home Assistant can run as a daemon within init.d with the script below.
## 1. Copy script
Copy either the daemon script or the Python environment script at the end of this page to `/etc/init.d/hass-daemon` depending on your installation.
After that, set the script to be executable:
```bash
sudo chmod +x /etc/init.d/hass-daemon
```
## 2. Select a user
Create or pick a user that the Home Assistant daemon will run under. Update script to set `RUN_AS` to the username that should be used to execute Home Assistant.
## 3. Change `hass` executable and other variables if required
Some installation environments may require a change in the Home Assistant executable `hass`. Update script to set `HASS_BIN` to the appropriate `hass` executable path. Please also check the other variables for the appropriate value. In general the defaults should work
## 4. Install this service
```bash
sudo service hass-daemon install
```
## 5. Create logrotate rule
This logrotate script at `/etc/logrotate.d/homeassistant` will create an outage of a few seconds every week at night. If you do not want this add `--log-rotate-days 7` to the `FLAGS` variable in the init script.
File `/var/log/homeassistant/home-assistant.log`:
```text
{
rotate 7
daily
missingok
notifempty
delaycompress
compress
postrotate
invoke-rc.d hass-daemon restart > /dev/null
endscript
}
```
### 6. Restart Machine
That's it. Restart your machine and Home Assistant should start automatically.
If Home Assistant does not start, check the log file output for errors at `/var/log/homeassistant/home-assistant.log`
### Extra: Running commands before Home Assistant executes
If any commands need to run before executing Home Assistant (like loading a virtual environment), put them in PRE_EXEC. This command must end with a semicolon.
### Daemon script
```bash
#!/bin/sh
### BEGIN INIT INFO
# Provides: hass
# Required-Start: $local_fs $network $named $time $syslog
# Required-Stop: $local_fs $network $named $time $syslog
# Default-Start: 2 3 4 5
# Default-Stop: 0 1 6
# Description: Home\ Assistant
### END INIT INFO
# /etc/init.d Service Script for Home Assistant
# Created with: https://gist.github.com/naholyr/4275302#file-new-service-sh
PRE_EXEC=""
# Typically /usr/bin/hass
HASS_BIN="hass"
RUN_AS="homeassistant"
PID_DIR="/var/run/hass"
PID_FILE="$PID_DIR/hass.pid"
CONFIG_DIR="/var/opt/homeassistant"
LOG_DIR="/var/log/homeassistant"
LOG_FILE="$LOG_DIR/home-assistant.log"
FLAGS="-v --config $CONFIG_DIR --pid-file $PID_FILE --log-file $LOG_FILE --daemon"
start() {
create_piddir
if [ -f $PID_FILE ] && kill -0 $(cat $PID_FILE) 2> /dev/null; then
echo 'Service already running' >&2
return 1
fi
echo -n 'Starting service… ' >&2
local CMD="$PRE_EXEC $HASS_BIN $FLAGS"
su -s /bin/bash -c "$CMD" $RUN_AS
if [ $? -ne 0 ]; then
echo "Failed" >&2
else
echo 'Done' >&2
fi
}
stop() {
if [ ! -f "$PID_FILE" ] || ! kill -0 $(cat "$PID_FILE") 2> /dev/null; then
echo 'Service not running' >&2
return 1
fi
echo -n 'Stopping service… ' >&2
kill $(cat "$PID_FILE")
while ps -p $(cat "$PID_FILE") > /dev/null 2>&1; do sleep 1;done;
rm -f $PID_FILE
echo 'Done' >&2
}
install() {
echo "Installing Home Assistant Daemon (hass-daemon)"
update-rc.d hass-daemon defaults
create_piddir
mkdir -p $CONFIG_DIR
chown $RUN_AS $CONFIG_DIR
mkdir -p $LOG_DIR
chown $RUN_AS $LOG_DIR
}
uninstall() {
echo "Are you really sure you want to uninstall this service? The INIT script will"
echo -n "also be deleted! That cannot be undone. [yes|No] "
local SURE
read SURE
if [ "$SURE" = "yes" ]; then
stop
remove_piddir
echo "Notice: The config directory has not been removed"
echo $CONFIG_DIR
echo "Notice: The log directory has not been removed"
echo $LOG_DIR
update-rc.d -f hass-daemon remove
rm -fv "$0"
echo "Home Assistant Daemon has been removed. Home Assistant is still installed."
fi
}
create_piddir() {
if [ ! -d "$PID_DIR" ]; then
mkdir -p $PID_DIR
chown $RUN_AS "$PID_DIR"
fi
}
remove_piddir() {
if [ -d "$PID_DIR" ]; then
if [ -e "$PID_FILE" ]; then
rm -fv "$PID_FILE"
fi
rmdir -v "$PID_DIR"
fi
}
case "$1" in
start)
start
;;
stop)
stop
;;
install)
install
;;
uninstall)
uninstall
;;
restart)
stop
start
;;
*)
echo "Usage: $0 {start|stop|restart|install|uninstall}"
esac
```
### Python virtual environment
```bash
#!/bin/sh
### BEGIN INIT INFO
# Provides: hass
# Required-Start: $local_fs $network $named $time $syslog
# Required-Stop: $local_fs $network $named $time $syslog
# Default-Start: 2 3 4 5
# Default-Stop: 0 1 6
# Description: Home\ Assistant
### END INIT INFO
# /etc/init.d Service Script for Home Assistant
# Created with: https://gist.github.com/naholyr/4275302#file-new-service-sh
PRE_EXEC="cd /srv/homeassistant; python3 -m venv .; source bin/activate;"
# Typically /usr/bin/hass
HASS_BIN="hass"
RUN_AS="homeassistant"
PID_DIR="/var/run/hass"
PID_FILE="$PID_DIR/hass.pid"
CONFIG_DIR="/home/$RUN_AS/.homeassistant"
LOG_DIR="/var/log/homeassistant"
LOG_FILE="$LOG_DIR/home-assistant.log"
FLAGS="-v --config $CONFIG_DIR --pid-file $PID_FILE --log-file $LOG_FILE --daemon"
start() {
create_piddir
if [ -f $PID_FILE ] && kill -0 $(cat $PID_FILE) 2> /dev/null; then
echo 'Service already running' >&2
return 1
fi
echo -n 'Starting service… ' >&2
local CMD="$PRE_EXEC $HASS_BIN $FLAGS"
su -s /bin/bash -c "$CMD" $RUN_AS
if [ $? -ne 0 ]; then
echo "Failed" >&2
else
echo 'Done' >&2
fi
}
stop() {
if [ ! -f "$PID_FILE" ] || ! kill -0 $(cat "$PID_FILE") 2> /dev/null; then
echo 'Service not running' >&2
return 1
fi
echo -n 'Stopping service… ' >&2
kill $(cat "$PID_FILE")
while ps -p $(cat "$PID_FILE") > /dev/null 2>&1; do sleep 1;done;
rm -f $PID_FILE
echo 'Done' >&2
}
install() {
echo "Installing Home Assistant Daemon (hass-daemon)"
update-rc.d hass-daemon defaults
create_piddir
mkdir -p $CONFIG_DIR
chown $RUN_AS $CONFIG_DIR
mkdir -p $LOG_DIR
chown $RUN_AS $LOG_DIR
}
uninstall() {
echo "Are you really sure you want to uninstall this service? The INIT script will"
echo -n "also be deleted! That cannot be undone. [yes|No] "
local SURE
read SURE
if [ "$SURE" = "yes" ]; then
stop
remove_piddir
echo "Notice: The config directory has not been removed"
echo $CONFIG_DIR
echo "Notice: The log directory has not been removed"
echo $LOG_DIR
update-rc.d -f hass-daemon remove
rm -fv "$0"
echo "Home Assistant Daemon has been removed. Home Assistant is still installed."
fi
}
create_piddir() {
if [ ! -d "$PID_DIR" ]; then
mkdir -p $PID_DIR
chown $RUN_AS "$PID_DIR"
fi
}
remove_piddir() {
if [ -d "$PID_DIR" ]; then
if [ -e "$PID_FILE" ]; then
rm -fv "$PID_FILE"
fi
rmdir -v "$PID_DIR"
fi
}
case "$1" in
start)
start
;;
stop)
stop
;;
install)
install
;;
uninstall)
uninstall
;;
restart)
stop
start
;;
*)
echo "Usage: $0 {start|stop|restart|install|uninstall}"
esac
```

35
source/_docs/autostart/macos.markdown
View File

@ -1,35 +0,0 @@
---
title: "Autostart on macOS"
description: "Instructions on how to setup Home Assistant to launch on Apple macOS."
redirect_from: /getting-started/autostart-macos/
---
Setting up Home Assistant to run as a background service is simple; macOS will start Home Assistant after the system has booted, the user has logged in, and make sure it's always running.
To get Home Assistant installed as a background service, run:
```bash
$ hass --script macos install
Home Assistant has been installed. Open it here: http://localhost:8123
```
Home Assistant will log to `~/Library/Logs/homeassistant.log`
Configuration is kept in `~/.homeassistant`
To uninstall the service, run:
```bash
$ hass --script macos uninstall
Home Assistant has been uninstalled.
```
Note:
`automake` is required for `hass` to start. If you are missing this on your system, you can install this by running:
```bash
$ brew install autoconf
```

44
source/_docs/autostart/synology.markdown
View File

@ -1,44 +0,0 @@
---
title: "Autostart on Synology NAS boot"
description: "Instructions on how to setup Home Assistant to launch on boot on Synology NAS."
redirect_from: /getting-started/autostart-synology/
---
To get Home Assistant to automatically start when you boot your Synology NAS:
SSH into your Synology & login as admin or root
```bash
$ cd /volume1/homeassistant
```
Create "homeassistant.conf" file using the following code
```bash
# only start this service after the httpd user process has started
start on started httpd-user
# stop the service gracefully if the runlevel changes to 'reboot'
stop on runlevel [06]
# run the scripts as the 'http' user. Running as root (the default) is a bad ide
#setuid admin
# exec the process. Use fully formed path names so that there is no reliance on
# the 'www' file is a node.js script which starts the foobar application.
exec /bin/sh /volume1/homeassistant/hass-daemon start
```
Register the autostart
```bash
ln -s homeassistant.conf /etc/init/homeassistant.conf
```
Make the relevant files executable:
```bash
chmod -r 777 /etc/init/homeassistant.conf
```
That's it - reboot your NAS and Home Assistant should automatically start

140
source/_docs/autostart/systemd.markdown
View File

@ -1,140 +0,0 @@
---
title: "Autostart using systemd"
description: "Instructions on how to setup Home Assistant to launch on boot using systemd."
redirect_from: /getting-started/autostart-systemd/
---
Newer Linux distributions are trending towards using `systemd` for managing daemons. Typically, systems based on Fedora, ArchLinux, or Debian (8 or later) use `systemd`. This includes Ubuntu releases including and after 15.04, CentOS, and Red Hat. If you are unsure if your system is using `systemd`, you may check with the following command:
```bash
$ ps -p 1 -o comm=
```
If the preceding command returns the string `systemd`, continue with the instructions below.
A service file is needed to control Home Assistant with `systemd`. The template below should be created using a text editor. Note, root permissions via `sudo` will likely be needed. The following should be noted to modify the template:
- `ExecStart` contains the path to `hass` and this may vary. Check with `whereis hass` for the location.
- For most systems, the file is `/etc/systemd/system/home-assistant@YOUR_USER.service` with YOUR_USER replaced by the user account that Home Assistant will run as (normally `homeassistant`). In particular, this is the case for Ubuntu 16.04.
- If unfamiliar with command-line text editors, `sudo nano -w [filename]` can be used with `[filename]` replaced with the full path to the file. Ex. `sudo nano -w /etc/systemd/system/home-assistant@YOUR_USER.service`. After text entered, press CTRL-X then press Y to save and exit.
- If you're running Home Assistant in a Python virtual environment or a Docker container, please skip to the appropriate template listed below.
```text
[Unit]
Description=Home Assistant
After=network-online.target
[Service]
Type=simple
User=%i
WorkingDirectory=/home/%i/.homeassistant
ExecStart=/usr/bin/hass
[Install]
WantedBy=multi-user.target
```
### Python virtual environment
If you've setup Home Assistant in `virtualenv` following our [Python installation guide](/getting-started/installation-virtualenv/) or [manual installation guide for Raspberry Pi](/getting-started/installation-raspberry-pi/), the following template should work for you. If Home Assistant install is not located at `/srv/homeassistant`, please modify the `ExecStart=` line appropriately. `YOUR_USER` should be replaced by the user account that Home Assistant will run as (e.g `homeassistant`).
```text
[Unit]
Description=Home Assistant
After=network-online.target
[Service]
Type=simple
User=%i
WorkingDirectory=/home/%i/.homeassistant
ExecStart=/srv/homeassistant/bin/hass -c "/home/%i/.homeassistant"
[Install]
WantedBy=multi-user.target
```
### Docker
If you want to use Docker, the following template should work for you.
```text
[Unit]
Description=Home Assistant
Requires=docker.service
After=docker.service
[Service]
Restart=always
RestartSec=3
ExecStart=/usr/bin/docker run --name=home-assistant-%i -v /home/%i/.homeassistant/:/config -v /etc/localtime:/etc/localtime:ro --net=host homeassistant/home-assistant
ExecStop=/usr/bin/docker stop -t 2 home-assistant-%i
ExecStopPost=/usr/bin/docker rm -f home-assistant-%i
[Install]
WantedBy=multi-user.target
```
### Next Steps
You need to reload `systemd` to make the daemon aware of the new configuration.
```bash
sudo systemctl --system daemon-reload
```
To have Home Assistant start automatically at boot, enable the service.
```bash
sudo systemctl enable home-assistant@YOUR_USER
```
To disable the automatic start, use this command.
```bash
sudo systemctl disable home-assistant@YOUR_USER
```
To start Home Assistant now, use this command.
```bash
sudo systemctl start home-assistant@YOUR_USER
```
You can also substitute the `start` above with `stop` to stop Home Assistant, `restart` to restart Home Assistant, and 'status' to see a brief status report as seen below.
```bash
$ sudo systemctl status home-assistant@YOUR_USER
● home-assistant@fab.service - Home Assistant for YOUR_USER
Loaded: loaded (/etc/systemd/system/home-assistant@YOUR_USER.service; enabled; vendor preset: disabled)
Active: active (running) since Sat 2016-03-26 12:26:06 CET; 13min ago
Main PID: 30422 (hass)
CGroup: /system.slice/system-home\x2dassistant.slice/home-assistant@YOUR_USER.service
├─30422 /usr/bin/python3 /usr/bin/hass
└─30426 /usr/bin/python3 /usr/bin/hass
[...]
```
To get Home Assistant's logging output, simple use `journalctl`.
```bash
sudo journalctl -f -u home-assistant@YOUR_USER
```
Because the log can scroll quite quickly, you can select to view only the error lines:
```bash
sudo journalctl -f -u home-assistant@YOUR_USER | grep -i 'error'
```
When working on Home Assistant, you can easily restart the system and then watch the log output by combining the above commands using `&&`
```bash
sudo systemctl restart home-assistant@YOUR_USER && sudo journalctl -f -u home-assistant@YOUR_USER
```
### Automatically restarting Home Assistant on failure
If you want to restart the Home Assistant service automatically after a crash, add the following lines to the `[Service]` section of your unit file:
```text
Restart=on-failure
RestartSec=5s
```

131
source/_docs/autostart/upstart.markdown
View File

@ -1,131 +0,0 @@
---
title: "Autostart using Upstart"
description: "Instructions on how to setup Home Assistant to launch on boot using Upstart."
---
Many Linux distributions use the Upstart system (or similar) for managing daemons. Typically, systems based on Debian 7 or previous use Upstart. This includes Ubuntu releases before 15.04. If you are unsure if your system is using Upstart, you may check with the following command:
```bash
ps -p 1 -o comm=
```
If the preceding command returns the string `init`, you are likely using Upstart.
Upstart will launch init scripts that are located in the directory `/etc/init.d/`. A sample init script for systems using Upstart could look like the sample below.
```bash
#!/bin/sh
### BEGIN INIT INFO
# Provides: hass
# Required-Start: $local_fs $network $named $time $syslog
# Required-Stop: $local_fs $network $named $time $syslog
# Default-Start: 2 3 4 5
# Default-Stop: 0 1 6
# Description: Home\ Assistant
### END INIT INFO
# /etc/init.d Service Script for Home Assistant
# Created with: https://gist.github.com/naholyr/4275302#file-new-service-sh
#
# Installation:
# 1) If any commands need to run before executing hass (like loading a
# virtual environment), put them in PRE_EXEC. This command must end with
# a semicolon.
# 2) Set RUN_AS to the username that should be used to execute hass.
# 3) Copy this script to /etc/init.d/
# sudo cp hass-daemon /etc/init.d/hass-daemon
# sudo chmod +x /etc/init.d/hass-daemon
# 4) Register the daemon with Linux
# sudo update-rc.d hass-daemon defaults
# 5) Install this service
# sudo service hass-daemon install
# 6) Restart Machine
#
# After installation, HA should start automatically. If HA does not start,
# check the log file output for errors.
# /var/opt/homeassistant/home-assistant.log
PRE_EXEC=""
RUN_AS="USER"
PID_FILE="/var/run/hass.pid"
CONFIG_DIR="/var/opt/homeassistant"
FLAGS="-v --config $CONFIG_DIR --pid-file $PID_FILE --daemon"
REDIRECT="> $CONFIG_DIR/home-assistant.log 2>&1"
start() {
if [ -f $PID_FILE ] && kill -0 $(cat $PID_FILE) 2> /dev/null; then
echo 'Service already running' >&2
return 1
fi
echo 'Starting service…' >&2
local CMD="$PRE_EXEC hass $FLAGS $REDIRECT;"
su -c "$CMD" $RUN_AS
echo 'Service started' >&2
}
stop() {
if [ ! -f "$PID_FILE" ] || ! kill -0 $(cat "$PID_FILE") 2> /dev/null; then
echo 'Service not running' >&2
return 1
fi
echo 'Stopping service…' >&2
kill -3 $(cat "$PID_FILE")
while ps -p $(cat "$PID_FILE") > /dev/null 2>&1; do sleep 1;done;
echo 'Service stopped' >&2
}
install() {
echo "Installing Home Assistant Daemon (hass-daemon)"
echo "999999" > $PID_FILE
chown $RUN_AS $PID_FILE
mkdir -p $CONFIG_DIR
chown $RUN_AS $CONFIG_DIR
}
uninstall() {
echo -n "Are you really sure you want to uninstall this service? That cannot be undone. [yes|No] "
local SURE
read SURE
if [ "$SURE" = "yes" ]; then
stop
rm -fv "$PID_FILE"
echo "Notice: The config directory has not been removed"
echo $CONFIG_DIR
update-rc.d -f hass-daemon remove
rm -fv "$0"
echo "Home Assistant Daemon has been removed. Home Assistant is still installed."
fi
}
case "$1" in
start)
start
;;
stop)
stop
;;
install)
install
;;
uninstall)
uninstall
;;
restart)
stop
start
;;
*)
echo "Usage: $0 {start|stop|restart|install|uninstall}"
esac
```
To install this script, download it, tweak it to you liking, and install it by following the directions in the header. This script will setup Home Assistant to run when the system boots. To start/stop Home Assistant manually, issue the following commands:
```bash
sudo service hass-daemon start
sudo service hass-daemon stop
```
When running Home Assistant with this script, the configuration directory will be located at `/var/opt/homeassistant`. This directory will contain a verbose log rather than simply an error log.
When running daemons, it is good practice to have the daemon run under its own username rather than the default user's name. Instructions for setting this up are outside the scope of this document.

4
source/_docs/configuration/remote.markdown
View File

@ -30,7 +30,3 @@ If you cannot access your Home Assistant installation remotely, remember to chec
Just putting a port up is not secure. You should definitely consider encrypting your traffic if you are accessing your Home Assistant installation remotely. For details please check the [set up encryption using Let's Encrypt](/blog/2017/09/27/effortless-encryption-with-lets-encrypt-and-duckdns/) blog post or this [detailed guide](/docs/ecosystem/certificates/lets_encrypt/) to using Let's Encrypt with Home Assistant.
</div>
Protect your communication with a [self-signed certificate](/docs/ecosystem/certificates/tls_self_signed_certificate/) between your client and the Home Assistant instance.
For another way to access your Home Assistant frontend, check out [the instructions how to use Tor](/docs/ecosystem/tor/).

2
source/_docs/configuration/securing.markdown
View File

@ -18,7 +18,7 @@ Here's the summary of what you *must* do to secure your Home Assistant system:
If you want secure remote access, the easiest option is to use [Home Assistant cloud](/cloud/) by which you also [support](https://www.nabucasa.com/about) the founders of Home Assistant.
Other options are to use TLS/SSL via the add-ons [Duck DNS integrating Let's Encrypt](/integrations/duckdns/) or [Let’s Encrypt](/docs/ecosystem/certificates/lets_encrypt/).
To expose your instance to the internet, use a [VPN](https://pivpn.dev/), [Tor](/docs/ecosystem/tor/) or an [SSH tunnel](/blog/2017/11/02/secure-shell-tunnel/). Make sure to expose the used port in your router.
To expose your instance to the internet, use a [VPN](https://pivpn.dev/), or an [SSH tunnel](/blog/2017/11/02/secure-shell-tunnel/). Make sure to expose the used port in your router.
### Extras for manual installations

8
source/_docs/ecosystem.markdown
View File

@ -1,8 +0,0 @@
---
title: "Ecosystem"
description: "External tools for Home Assistant"
redirect_from: /ecosystem/
---
Ecosystem includes documentation for related tools and projects that extend Home Assistant to new platforms and systems.

116
source/_docs/ecosystem/apache.markdown
View File

@ -1,116 +0,0 @@
---
title: "Apache Proxy"
description: "Configure Apache to work with Home Assistant as a subdomain"
redirect_from: /cookbook/apache_configuration/
---
This example demonstrates how you can configure Apache to act as a proxy for Home Assistant.
This is useful if you want to have:
* a subdomain redirecting to your Home Assistant instance
* several subdomain for several instance
* HTTPS redirection
#### Subdomain
So you already have a working Apache server available at example.org. Your Home Assistant is correctly working on this web server and available at `http://localhost:8123`
Enable [`mod_proxy_wstunnel`](https://httpd.apache.org/docs/2.4/mod/mod_proxy_wstunnel.html) by running if you encounter issues while serving Home Assistant through your proxy:
```bash
$ sudo a2enmod proxy_wstunnel
```
To be able to access to your Home Assistant instance by using `https://home.example.org`, add the following file to `/etc/httpd/conf/extra/` as `hass.conf`
```text
<VirtualHost *:443>
ServerName home.example.org
ProxyPreserveHost On
ProxyRequests off
ProxyPass /api/websocket ws://localhost:8123/api/websocket
ProxyPassReverse /api/websocket ws://localhost:8123/api/websocket
ProxyPass / http://localhost:8123/
ProxyPassReverse / http://localhost:8123/
RewriteEngine on
RewriteCond %{HTTP:Upgrade} =websocket [NC]
RewriteRule /(.*) ws://localhost:8123/$1 [P,L]
RewriteCond %{HTTP:Upgrade} !=websocket [NC]
RewriteRule /(.*) http://localhost:8123/$1 [P,L]
</VirtualHost>
```
and make sure that this file is read by Apache's main configuration file `/etc/httpd/conf/httpd.conf`
```text
...
Include conf/extra/hass.conf
...
```
If you don't want HTTPS, you can change `<VirtualHost *:443>` to `<VirtualHost *:80>` or better consider redirecting all HTTP to HTTPS.
<div class='note'>
In case you are getting occasional HTTP 504 error messages ("Gateway Timeout") or HTTP 502 messages ("Bad Gateway") when accessing the Web UI through your proxy, try adding disablereuse=on to both ProxyPass directives:
</div>
```text
<VirtualHost *:443>
[...]
ProxyPass /api/websocket ws://localhost:8123/api/websocket disablereuse=on
[...]
ProxyPass / http://localhost:8123/ disablereuse=on
[...]
</VirtualHost>
```
#### Multiple Instance
You already have Home Assistant running on `http://localhost:8123` and available at home.example.org as describe before. The configuration file for this Home Assistant is available in `/home/alice/.homeassistant/configuration.yaml`
You want another instance available at `https://countryside.example.org`
You can either :
* Create a new user, `bob`, to hold the configuration file in `/home/bob/.homeassistant/configuration.yaml` and run Home Assistant as this new user
* Create another configuration directory in `/home/alice/.homeassistan2/configuration.yaml` and run Home Assistant using `hass --config /home/alice/.homeassistant2/`
In both solution, change port number used by modifying `configuration.yaml`
```yaml
http:
server_port: 8124
...
```
Start Home Assistant: Now, you have another instance running on `http://localhost:8124`
To access this instance by using `https://countryside.example.org` add to `/etc/httpd/conf/extra/hass.conf`
```text
<VirtualHost *:443>
ProxyPreserveHost On
ProxyRequests Off
ServerName countryside.example.org
ProxyPass /api/websocket ws://localhost:8123/api/websocket
ProxyPassReverse /api/websocket ws://localhost:8123/api/websocket
ProxyPass / http://localhost:8124/
ProxyPassReverse / http://localhost:8124/
</VirtualHost>
```
#### HTTP to HTTPS redirection
Add to your `/etc/httpd/conf/extra/hass.conf`
```text
<VirtualHost *:80>
ServerName example.org
ServerSignature Off
RewriteEngine on
RewriteCond %{HTTPS} !=on
RewriteRule .* https://%{SERVER_NAME}%{REQUEST_URI} [NE,R,L]
</VirtualHost>
```

65
source/_docs/ecosystem/backup/backup_dropbox.markdown
View File

@ -1,65 +0,0 @@
---
title: "Configuration Backup to Dropbox"
description: "Instructions on how backup your Home Assistant configuration to Dropbox"
redirect_from: /cookbook/dropboxbackup/
---
Backing up and regularly syncing your Home Assistant configuration to [Dropbox](http://dropbox.com) is similar to [GitHub Backup](/docs/ecosystem/backup/backup_github/)
## Requirements
You need two parts in order to get it working correctly.
Become the user that run Home Assistant.
- A separate Python script that syncs a specific folder. Which can be found [here](https://gist.github.com/riemers/31e3350041fd3e47e489cbc811209d6f)
- The excellent [dropbox uploader script](https://github.com/andreafabrizi/Dropbox-Uploader/blob/master/dropbox_uploader.sh) you can grab the .sh file only.
Download those files to a folder of your liking, after that edit both files and change paths accordingly.
In the Python script you can specify which files and directories should be excluded. This allows you to skip `secrets.yaml` or the `deps` folder.
### Step 1: Linking your Dropbox account
```bash
chmod +x dropbox_uploader.sh
./dropbox_uploader.sh
```
Follow the instructions you see on your screen.
### Step 2: Running the Dropbox uploader
Go to the folder you have placed `dropbox.py`.
- **Option A:**
Copy file `dropbox_uploader.sh` to : `.homeassistant/extraconfig/shell_code/` (so the full path would be similar to: `/home/homeassistant/.homeassistant/extraconfig/shell_code/dropbox_uploader.sh`)
- **Option B:**
Edit `dropbox.py`:
Change the following line:
```txt
uploader = "/home/homeassistant/.homeassistant/extraconfig/shell_code/dropbox_uploader.sh"
```
to where you placed your file: (for example):
```txt
uploader = "/home/homeassistant/MyFolder/dropbox_uploader.sh"
```
```bash
python dropbox.py
```
The first time can take a lot of time since it will upload all your files!
Do note, this will **backup your passwords to Dropbox**.
### Automate the backup
So you just made a full backup, next time you want it to be done automatically. Since your database can change and so do other files over time.
Add it to your crontab, edit the **path/to** part.
```bash
(crontab -l 2>/dev/null; echo "0 3 * * * python /path/to/dropbox.py") | crontab -
```

216
source/_docs/ecosystem/backup/backup_github.markdown
View File

@ -1,216 +0,0 @@
---
title: "Configuration Backup to GitHub"
description: "Instructions on how backup your Home Assistant configuration to GitHub"
redirect_from: /cookbook/githubbackup/
---
Backing up and regularly syncing your Home Assistant configuration to [GitHub](http://GitHub.com) has several benefits:
- A remote copy of your Home Assistant YAML files in case you need to recover.
- A documented history of your changes for troubleshooting purposes.
- It will help the Home Assistant community learn from your configuration examples.
<div class='note'>
This is not a comprehensive tutorial on using GitHub, more information can be found in the [GitHub Help](https://help.github.com/) pages. This guide assumes the user has an intermediate experience level and is comfortable with such concepts as: navigating the Home Assistant directory structure, logging in as the Home Assistant user, and working with the command line.
</div>
<div class='note'>
This will not create a full backup of your Home Assistant files or your OS. In addition to backing up to Github, you should consider having regular backups of all your Home Assistant configuration files and images of your SD card if applicable.
</div>
### Important Best Practices
Some best practices to consider before putting your configuration on GitHub:
- Extensive use of [`secrets.yaml`](/docs/configuration/secrets/) to hide sensitive information like usernames, passwords, device information, and location.
- Exclusion of some files, including `secrets.yaml` and device-specific information using a [`.gitignore`](https://git-scm.com/docs/gitignore) file.
- Regularly committing your configuration to GitHub to make sure that your backup is up to date.
- Use a README.md to document your configuration and include screenshots of your Home Assistant frontend.
### Step 1: Installing and Initializing Git
In order to put your configuration on GitHub, you must install the Git package on your Home Assistant server (instructions below will work on Raspberry Pi, Ubuntu or any Debian-based system) *Note: this isn't required in Hass.io, it's included as default so proceed to step 2*:
```bash
sudo apt-get update
sudo apt-get install git
```
### Step 2: Creating `.gitignore`
<div class='note warning'>
Before creating and pushing your Home Assistant configuration to GitHub, please make sure to follow the [`secrets.yaml`](/docs/configuration/secrets/) best practice mentioned above and scrub your configuration for any passwords or sensitive information.
</div>
Creating a `.gitignore` file in your repository will tell Git which files NOT to push to the GitHub server. This should be used to prevent publishing sensitive files to the public. It should contain a list of filenames and pattern matches. This list should include at least your [`secrets.yaml`](/docs/configuration/secrets/) file, device configuration files, and the Home Assistant database/directory structure. The `.gitignore` file should be placed in the root of your Home Assistant configuration directory: `<config dir>/.gitignore`.
<div class='note'>
If you are creating the `.gitignore` file on Windows, make sure that you save the file with Unix line endings (i.e., by using an editor like Notepad++).
</div>
Here is an example that will ignore everything but your YAML configuration.
```bash
# Example .gitignore file for your config dir.
# An * ensures that everything will be ignored.
*
# You can whitelist files/folders with !, these will not be ignored.
!*.yaml
!.gitignore
!*.md
# Ignore folders.
.storage
.cloud
.google.token
# Ensure these YAML files are ignored, otherwise your secret data/credentials will leak.
ip_bans.yaml
secrets.yaml
known_devices.yaml
```
<div class='note'>
You might read this guide too late and accidentally already have your secrets published. It is not enough to just remove them with a new commit. Git is a version control system and keeps history. You need to delete your repository and start a new one. Also change all passwords and revoke the API keys that were public.
</div>
More information on the layout of the file can be found in the [.gitignore manual](https://git-scm.com/docs/gitignore).
### Step 3: Preparing your Home Assistant directory for GitHub
In your Home Assistant directory, type the following commands as the Home Assistant user, replacing the email address and name with your information:
```bash
git init
git config user.email "you@example.com"
git config user.name "Your Name"
git add .
git commit
```
After the `git commit` command, you will be asked to enter a message for the commit. This will add a comment beside each file on GitHub describing the purpose for the commit. In this case, you can enter something like "Initial commit of my Home Assistant configuration". To exit the editor, press `CTRL + C` and then `:wq` which will exit and save the changes.
### Step 4: Creating Repository on GitHub
- Connect to [GitHub](https://github.com) and login to your account (or create an account if you don't already have one).
- Click "[New Repository](https://github.com/new)" and give your repository a name/description (`Home-AssistantConfig` is used in the example below). You do NOT need to change any other options.
- Click "Create Repository"
### Step 5: Your initial commit to GitHub
Once you are sure you are using `secrets.yaml` and `.gitignore` correctly, it is time to push your configuration to the GitHub Repository that you just created.
In your Home Assistant directory, type the following commands as the Home Assistant user, replacing "username" in the URL with your GitHub username:
```bash
git remote add origin https://github.com/username/Home-AssistantConfig
git push -u origin master
```
You will be asked to enter your GitHub username and password (or ssh key passphrase if you use [GitHub with ssh](https://help.github.com/categories/ssh/)).
Congratulations, you now have a copy of your current Home Assistant Configuration on GitHub!
### Step 6: Keeping your repository up to date
You should update your repository on a regular basis. Ideally after you make a major configuration change (new device, new component, etc.). The below script will update your repository with any changed configuration files and allow you to add a comment with the commit for tracking purposes:
<div class='note'>
You may need to adjust the paths in the script depending on your Home Assistant configuration.
</div>
`gitupdate.sh`
```bash
#!/bin/bash
cd /home/homeassistant/.homeassistant
source /srv/homeassistant/bin/activate
hass --script check_config
git add .
git status
echo -n "Enter the Description for the Change: " [Minor Update]
read CHANGE_MSG
git commit -m "${CHANGE_MSG}"
git push origin master
exit
```
Every time you run this script, you will be prompted for a comment to describe the change(s) that you are committing. This comment will be displayed beside each changed file on GitHub and will be stored after each commit. You will also be asked to enter your GitHub username and password (or SSH key passphrase if you use [GitHub with SSH](https://help.github.com/categories/ssh/)).
### Step 7: Configuration file testing
[Travis CI](https://travis-ci.org) is a continuous integration testing system that runs every time the code in your repository is updated and allows you to validate that your code works on a fresh install.
- [Authorize Travis CI](https://travis-ci.org/auth) to have access to your GitHub repositories.
- Create the build script that Travis will run to test your repository.
- Create a dummy `secrets.yaml` for Travis.
Example .travis.yml
```yaml
language: python
python:
- "3.7"
before_install:
- mv travis_secrets.yaml secrets.yaml
- sudo apt-get install -y libudev-dev
install:
- pip3 install homeassistant
script:
- hass -c . --script check_config
```
Since the `secrets.yaml` should _not_ be stored in your repository for security reasons, you won't be able to access it at build time. Creating a dummy `secrets.yaml` is as simple as creating a new file that mimics your existing `secrets.yaml` with the required keys, but not their value.
```yaml
#travis_secrets.yaml
http_api: 000000000000000000000000
home_latitude: 00.00000
home_longitude: 00.0000
home_elevation: 0
```
### Extra commands
You can enter these commands to get a list of the files in your local Git repository and a status of files that have changed but not committed yet:
```bash
git ls-files
git status
```
Examples:
```bash
homeassistant@raspberrypi:~/.homeassistant $ git ls-files
.gitignore
README.md
automation.yaml
configuration.yaml
customize.yaml
device_tracker.yaml
group.yaml
script.yaml
homeassistant@raspberrypi:~/.homeassistant $ git status
On branch master
Your branch is up-to-date with 'origin/master'.
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)
modified: .gitignore
modified: automation.yaml
modified: customize.yaml
modified: group.yaml
no changes added to commit (use "git add" and/or "git commit -a")
```

112
source/_docs/ecosystem/backup/backup_usb.markdown
View File

@ -1,112 +0,0 @@
---
title: "Configuration Backup to USB drive"
description: "Instructions on how backup your Home Assistant configuration to USB drive"
---
This will step you through the process of setting up a backup of your Home Assistant configuration to a USB device. This is a good method if you don't want to mask all of your passwords since the backup is kept locally at your home/residence.
### Requirements
First, you need a USB drive. It should be formatted properly for your device and connected to your device before beginning. Any type of partition will work, but Linux filesystems are preferred so that you can set permissions.
Once connected you want to mount the drive. To find the path where it is located, you can use the `dmesg` command.
```bash
# dmesg | grep sd
[ 0.909712] sdhci: Secure Digital Host Controller Interface driver
[ 0.916414] sdhci: Copyright(c) Pierre Ossman
[ 0.923366] sdhost: log_buf @ bac07000 (fac07000)
[ 0.989001] mmc0: sdhost-bcm2835 loaded - DMA enabled (>1)
[ 1.049095] sdhci-pltfm: SDHCI platform and OF driver helper
[726257.743301] sd 0:0:0:0: Attached scsi generic sg0 type 0
[726259.184810] sd 0:0:0:0: [sda] 124846080 512-byte logical blocks: (63.9 GB/59.5 GiB)
[726259.185603] sd 0:0:0:0: [sda] Write Protect is off
[726259.185613] sd 0:0:0:0: [sda] Mode Sense: 23 00 00 00
[726259.186432] sd 0:0:0:0: [sda] No Caching mode page found
[726259.186445] sd 0:0:0:0: [sda] Assuming drive cache: write through
[726259.206085] sda: sda1
[726259.209004] sd 0:0:0:0: [sda] Attached SCSI removable disk
```
The device here is `sda` and our partition is `sda1`. So our partition is located here `/dev/sda1`.
Mount the drive (as root) to `/media`
```bash
# sudo mount /dev/sda1 /media/
```
### Prepare the USB Device
Change to the `/media` directory and create a folder called `hassbackup`. Change the ownership to the user that runs Home Assistant. In this example case, the user and group are both `homeassistant`.
```bash
# cd /media/
/media# mkdir hassbackup
/media# chown homeassistant:homeassistant hassbackup/
/media# ls -al
total 28
drwxr-xr-x 4 root root 4096 Apr 29 10:36 .
drwxr-xr-x 22 root root 4096 Mar 22 18:37 ..
drwxr-xr-x 2 homeassistant homeassistant 4096 Apr 29 10:36 hassbackup
drwx------ 2 root root 16384 Apr 29 10:18 lost+found
```
### Install Dependency
The script in the next section uses zip to preserve space on your drive. So we will install zip next.
```bash
/media# apt-get install zip
Reading package lists... Done
Building dependency tree
[...]
Setting up zip (3.0-8) ...
```
### Download and Run Script
Become the `homeassistant` user (or whatever user runs Home Assistant). Change to whatever directory you would like the [script](https://gist.github.com/riemers/041c6a386a2eab95c55ba3ccaa10e7b0) placed into and run the following command.
```bash
# wget https://gist.githubusercontent.com/riemers/041c6a386a2eab95c55ba3ccaa10e7b0/raw/86727d4e72e9757da4f68f1c9d784720e72d0e99/usb_backup.sh
```
Make the downloaded script executable.
```bash
# chmod +x usb_backup.sh
```
Edit the script file using your preferred text editor (use nano if you are not advanced). Change the paths to reflect your configuration, then simply run `./usb_backup.sh`.
```bash
$ .homeassistant/extraconfig/shell_code/usb_backup.sh
[i] Creating backup
[i] Backup complete: /media/hassbackup/hass-config_20170429_112728.zip
[i] Keeping all files no prunning set
```
### Set Up Crontab
To automatically backup your configuration on a schedule, you can add a crontab for it as the `homeassistant` user.
Change the path below to the directory where you placed the `usb_backup.sh` and run the following line. This will backup every night at 3 am.
```bash
(crontab -l 2>/dev/null; echo "0 3 * * * /home/homeassistant/.homeassistant/extraconfig/shell_code/usb_backup.sh") | crontab -
```
### Auto Mount the USB Device
NOTE: This does not automatically mount your USB drive at boot. You will need to manually mount your drive after each boot or add a line to your `/etc/fstab` file.
To manually mount a USB drive located at `/dev/sda1`, run the following line:
```bash
# mount /dev/sda1 /media
```
Alternatively, auto-mount the drive by adding the following entry to your `/etc/fstab`:
```text
/dev/sda1 /media ext4 defaults,noatime 0 1
```

57
source/_docs/ecosystem/caddy.markdown
View File

@ -1,57 +0,0 @@
---
title: "Caddy Server reverse proxy"
description: "Configure Caddy Server as a reverse proxy to Home Assistant."
---
[Caddy Server](https://caddyserver.com/) is a powerful HTTP/2 server, that enables HTTPS by default with automatically generated Let's Encrypt certificates, which allows a simple configuration procces.
Using Caddy as a proxy for Home Assistant allows you to serve Home Assistant securely over standard ports. This configuration file and instructions will walk you through setting up Home Assistant over a secure connection.
### 1. Get a domain name forwarded to your IP
Chances are, you have a dynamic IP address (your ISP changes your address periodically). If this is true, you can use a Dynamic DNS service to obtain a domain and set it up to update with you IP. If you purchase your own domain name, you will be able to easily get a trusted SSL certificate later.
### 2. Install Caddy on your server
This will vary depending on your OS. Caddy has a [nice utillity](https://caddyserver.com/download) that generates an installer script.
<div class='note'>
Make sure you include the `hook.service` plugin if you want to run Caddy as a service
</div>
### 3. Port forwarding.
Forward ports 443 and 80 to your server on your router. Do not forward port 8123.
### 4. Create Caddyfile.
Use this as your Caddyfile, change the domain name to match yours.
```text
example.com {
proxy / localhost:8123 {
websocket
transparent
}
}
```
### 5. Configure Home Assistant
Home Assistant is still available without using the Caddy proxy. Restricting it to only listen to `127.0.0.1` will forbid direct accesses. Also, Home Assistant should be told to trust headers coming from Caddy proxy only. Otherwise, incoming requests will always come from `127.0.0.1` and not the real IP address.
On your `configuration.yaml` file, edit the `http` component.
```yaml
http:
# For extra security set this to only accept connections on localhost if Caddy is on the same machine
# server_host: 127.0.0.1
use_x_forwarded_for: true
# You must set the trusted proxy IP address so that Home Assistant will properly accept connections
# Set this to your Caddy machine IP, or localhost if hosted on the same machine.
trusted_proxies: <Caddy IP address here, or 127.0.0.1 if hosted on the same machine>
```
### 6. Start Caddy
You can either start Caddy or [install it as a service](https://github.com/mholt/caddy/wiki/Caddy-as-a-service-examples), pass the Caddyfile path as a `conf` parameter.
Home Assistant will be listening on port 443 (HTTPS) and all insecure traffic on port 80 will be redirected.

8
source/_docs/ecosystem/certificates.markdown
View File

@ -1,8 +0,0 @@
---
title: "Certificates"
description: "Protect your communication with Home Assistant."
---
If you plan to expose your Home Assistant to the internet or want an extra layer of protection in your local network, consider to use SSL/TLS. This way you can protect your communication. Especially sensitive data like usernames and passwords are encrypted between the endpoints.
Setting up usually requires creating the certificate and configure the [`http`](/integrations/http/) component.

554
source/_docs/ecosystem/certificates/lets_encrypt.markdown
View File

@ -1,554 +0,0 @@
---
title: "Remote Access with TLS/SSL via Let's Encrypt"
description: "A guide to remotely accessing Home Assistant and securing the connection with an SSL certificate from Let's Encrypt"
---
<div class='note'>
This guide is for users running Home Assistant Core.
If you are using Home Assistant do not use this guide. Instead, use the [DuckDNS add-on](/addons/duckdns/) for Home Assistant.
</div>
This guide was added by mf_social on 16/03/2017 and was valid at the time of writing. This guide makes the following assumptions:
- You can access your Home Assistant instance across your local network, and access the device that it is on via SSH from your local network.
- You know the internal IP address of your router and can access your router's configuration pages.
- You have already secured your Home Assistant instance, following the advice on [this page](/docs/configuration/securing/)
- You want to access your Home Assistant instance when you are away from home (ie, not connected to your local network) and secure it with a TLS/SSL certificate.
- You have a basic understanding of the phrases I have used so far.
- You are not currently running anything on port 80 on your network (you'd know if you were).
- If you are not using Home Assistant on a Debian/Raspian system you will be able to convert any of the terminology I use in to the correct syntax for your system.
- You understand that this is a 'guide' covering the general application of these things to the general masses and there are things outside of the scope of it, and it does not cover every eventuality (although I have made some notes where people may stumble). Also, I have used some turns of phrase to make it easier to understand for the novice reader which people of advanced knowledge may say is inaccurate. My goal here is to get you through this guide with a satisfactory outcome and have a decent understanding of what you are doing and why, not to teach you advanced internet communication protocols.
- Each step presumes you have fully completed the previous step successfully, so if you did an earlier step following a different guide, please ensure that you have not missed anything out that may affect the step you have jumped to, and ensure that you adapt any commands to take in to account different file placements from other guides.
Steps we will take:
- 0 - Gain a basic level of understanding around IP addresses, port numbers and port forwarding
- 1 - Set your device to have a static IP address
- 2 - Set up port forwarding without TLS/SSL and test connection
- 3 - Set up a DuckDNS account
- 4 - Obtain a TLS/SSL certificate from Let's Encrypt
- 5 - Check the incoming connection
- 6 - Clean up port forwards
- 7 - Set up a sensor to monitor the expiry date of the certificate
- 8 - Set up an automatic renewal of the TLS/SSL certificate
- 9 - Set up an alert to warn us if something went wrong
### 0 - Gain a basic level of understanding around IP addresses, port numbers and port forwarding
An IP address is a bit like a phone number. When you access your Home Assistant instance you type something similar to 192.168.0.200:8123 in to your address bar of your browser. The bit before the colon is the IP address (in this case 192.168.0.200) and the bit after is the port number (in this case 8123). When you SSH in to the device running Home Assistant you will use the same IP address, and you will use port 22. You may not be aware that you are using port 22, but if you are using Putty look in the box next to where you type the IP address, you will see that it has already selected port 22 for you.
So, if an IP address is like a phone number, a port number is like an extension number. An analogy would be if you phone your local doctors on 192-1680-200 and the receptionist answers, you ask to speak to Dr. Smith and she will put you through to extension 8123, which is the phone Dr. Smith is sitting at. The doctors surgery is the device your Home Assistant is running on, Dr. Smith is your Home Assistant. Thusly, your Home Assistant instance is 'waiting for your call' on port 8123, at the device IP 192.168.0.200 .
Now, to speak to the outside world your connection goes through a router. Your router will have two IP addresses. One is the internal network number, most likely 192.168.0.1 in my example, and an external IP address that incoming traffic is sent to. In the example of calling the doctors, the external IP is your telephone number's area code.
So, when we want to connect to our Home Assistant instance from outside our network we will need to call the correct extension number, at the correct phone number, in the correct area code.
We will be looking for a system to run like this (in this example I will pretend our external IP is 203.0.113.12):
```text
Outside world -> 203.0.113.12:8123 -> your router -> 192.168.0.200:8123
```
Sounds simple? It really is except for two small, but easy to overcome, complications:
- IP addresses are often dynamically allocated, so they can change.
- Because of the way the internet works you cannot chain IP addresses together to get from where you are, to where you want to go.
To get around the issue of changing IP addresses we must remember that there are two IP addresses affected. Your external one (which we will 'call' to get on to your network from the internet) and your internal one (192.168.0.200 in the example I am currently using).
So, we can use a static IP to ensure that whenever our device running Home Assistant connects to our router it always uses the same address. This way our internal IP never changes. This is covered in step 1 below.
We then have no control over our external IP, as our Service Provider will give us a new one at random intervals. To fix this we will use a service called DuckDNS which will give us a name for our connection (something like examplehome.duckdns.org) and behind the scenes will continue to update your external IP. So no matter how many times the IP address changes, typing examplehome.duckdns.org in to our browser will convert to the correct, up-to-date, IP address. This is covered in step 3 below.
To get around the issue of not being able to chain the IP addresses together (I can't say I want to call 203.0.113.12 and be put through to 192.168.0.200, and then be put through to extension 8123) we use port forwarding. Port forwarding is the process of telling your router which device to allow the outside connection to speak to. In the doctors surgery example, port forwarding is the receptionist. This takes a call from outside, and forwards it to the correct extension number inside. It is important to note that port forwarding can forward an incoming request for one port to a different port on your internal network if you so choose, and we will be doing this later on. The end result being that when we have our TLS/SSL certificate our incoming call will by default be requesting port 443 (because that is the default HTTPS port, like the default SSH port is 22), our port forwarding rule can forward this to our Home Assistant instance on port 8123 (or we can specify the port number in the URL). When this guide is completed we will run something like this:
```text
Outside world -> https://examplehome.duckdns.org -> 203.0.113.12:443 -> your router -> 192.168.0.200:8123
```
So, let's make it happen...
### 1 - Set your device to have a static IP address
Whenever a device is connected to a network it has an IP address. This IP address is often dynamically assigned to the device on connection. This means there are occasions where the IP address you use to access Home Assistant, or SSH in to the device running Home Assistant, may change. Setting a static IP address means that the device will always be on the same address.
SSH in to your system running Home Assistant and login.
Type the following command to list your network interfaces:
```bash
ifconfig
```
You will receive an output similar to the image below:
<p class='img'>
<img src='/images/screenshots/ip-set.jpg' />
Screenshot
</p>
Make a note of the interface name and the IP address you are currently on. In the picture it is the wireless connection that is highlighted, but with your setup it may be the wired one (eth0 or similar), make sure you get the correct information.
Then type the following command to open the text file that controls your network connection:
```bash
sudo nano /etc/dhcpcd.conf
```
At the bottom of the file add the following lines:
```text
interface wlan0 <----- or the interface you just wrote down.
static ip_address=192.168.0.200/24 <---- the IP address you just wrote down with a '/24' at the end
static routers=192.168.0.1 <---- Your router's IP address
static domain_name_servers=192.168.0.1 <---- Your router's IP address
```
It is important to note that the first three bytes of your static IP address and your router's IP address should be the same, e.g.:
```text
Router: 192.168.0.1
Yes
HA IP: 192.168.0.200
No
HA IP: 192.175.96.200
```
Press Ctrl + x to close the editor, pressing Y to save the changes when prompted.
Reboot your device running HA:
```bash
sudo reboot
```
When it comes back up check that you can SSH in to it again on the IP address you wrote down.
Make sure Home Assistant is running and access it via the local network by typing the IP address and port number in to the browser:
```text
http://192.168.0.200:8123.
```
All working? Hooray! You now have a static IP. This will now always be your internal IP address for your Home Assistant device. This will be known as YOUR-HA-IP for the rest of this guide.
### 2 - Set up port forwarding without TLS/SSL and test connection
Log in to your router's configuration pages and find the port forwarding options. This bit is hard to write a guide for because each router has a different way of presenting these options. Searching Google for "port forwarding" and the name of your router may help. When you find it you will likely have options similar to:
Service name - Port Range - Local IP - Local Port - Protocol
You may also have other options (like 'source IP'), these can usually be left blank or in their default state.
Set the port forwarding to:
```text
Service name - ha_test
Port Range - 8123
Local IP - YOUR-HA-IP
Local Port - 8123
Protocol - Both
```
Then save the change. On my router you have to fill these values in, then press an 'add' button to add the new rule to the list, then save the changes. All routers have a different interface, but you must ensure that these rules are saved at this point. If you are unsure, you can reboot the router and log back in, if the rule is present it was saved, if not, it wasn't!
Once you have saved this rule, go to your browser, and go to:
```text
https://whatismyipaddress.com/
```
This will tell you your current external IP address
Type the external IP address in to the URL bar with `http://` in front and :8123 after like so (203.0.113.12 is my example!):
```text
http://203.0.113.12:8123
```
Can you see your Home Assistant instance? If not, your router may not support 'loopback' - try the next step anyway and if that works, and this one still doesn't, just remember that you cannot use loopback, so will have to use internal addresses when you're on your home network. More on this later on if it's relevant to you.
Just to verify this isn't some kind of witchcraft that is actually using your internal network, pick up your phone, disconnect it from your Wi-Fi so that you are on your mobile data and not connected to the home network, put the same URL in the browser on your phone.
Can you see it now, from a device that is definitely not connected to your local network? Excellent! You now have a remotely accessible Home Assistant instance.
But what if your external IP changes? Plus, remembering all those numbers is pretty hard, isn't it? Read on to get yourself set up with a word-based URL at DuckDNS that will track any changes to your IP address so you don't have to stress anymore.
### 3 - Set up a DuckDNS account
Open your browser and go to <https://duckdns.org>.
Sign in and create an account using one of the id validation options in the top right corner.
In the domains section pick a name for your subdomain, this can be anything you like, and click add domain.
The URL you will be using later to access your Home Assistant instance from outside will be the subdomain you picked, followed by duckdns.org . For our example we will say our URL is examplehome.duckdns.org
Set up Home Assistant to keep your DuckDNS URL and external IP address in sync. In your `configuration.yaml` file add the following:
```yaml
duckdns:
domain: examplehome
access_token: abcdefgh-1234-abcd-1234-abcdefgh
```
The access token is available on your DuckDNS page. Restart Home Assistant after the change.
What you have now done is set up DuckDNS so that whenever you type examplehome.duckdns.org in to your browser it will convert that to your router's external IP address. Your external IP address will always be up to date because Home Assistant will update DuckDNS every time it changes.
Now type your new URL in to your address bar on your browser with port 8123 on the end:
```text
http://examplehome.duckdns.org:8123
```
What now happens behind the scenes is this:
- DuckDNS receives the request and forwards the request to your router's external IP address (which has been kept up to date by your device running Home Assistant)
- Your router receives the request on port 8123 and checks the port forwarding rules
- It finds the rule you created in step 2 and forwards the request to your Home Assistant instance
- Your browser displays your Home Assistant instance frontend.
Did it work? Super!
You now have a remotely accessible Home Assistant instance that has a text-based URL and will not drop out if your service provider changes your IP. But, it is only as secure as the password you set, which can be snooped during your session by a malicious hacker with relative ease. So we need to set up some encryption with TLS/SSL, read on to find out how.
### 4 - Obtain a TLS/SSL certificate from Let's Encrypt
First we need to set up another port forward like we did in step 2. Set your new rule to:
```text
Service name - ha_letsencrypt
Port Range - 80
Local IP - YOUR-HA-IP
Local Port - 80
Protocol - Both
```
Remember to save the new rule.
<div class='note'>
In cases where your ISP blocks port 80 you will need to change the port forward options to forward port 443 from outside to port 443 on your Home Assistant device. Please note that this will limit your options for automatically renewing the certificate, but this is a limitation because of your ISP setup and there is not a lot we can do about it!
</div>
Now SSH in to the device your Home Assistant is running on.
<div class='note'>
If you're running the 'standard' setup on a Raspberry Pi the chances are you just logged in as the 'pi' user. If not, you may have logged in as the Home Assistant user. There are commands below that require the Home Assistant user to be on the `sudoers` list. If you are not using the 'standard' Pi setup it is presumed you will know how to get your Home Assistant user on the `sudoers` list before continuing. If you are running the 'standard' Pi setup, from your 'pi' user issue the following command (where `homeassistant` is the Home Assistant user):
```bash
sudo adduser homeassistant sudo
```
</div>
If you did not already log in as the user that currently runs Home Assistant, change to that user (usually `homeassistant` or `hass` - you may have used a command similar to this in the past):
```bash
sudo -u homeassistant -H -s
```
Make sure you are in the home directory for the Home Assistant user:
```bash
cd
```
We will now install the certbot software:
```bash
sudo apt-get install certbot -y
```
You might need to stop Home Assistant before continuing with the next step. You can do this via the Web-UI or use the following command if you are running on Raspbian:
```bash
sudo systemctl stop home-assistant@homeassistant.service
```
You can restart Home Assistant after the next step using the same command and replacing `stop` with `start`.
Now we will run the certbot program to get our SSL certificate. You will need to include your email address and your DuckDNS URL in the appropriate places:
```bash
sudo certbot certonly --standalone --preferred-challenges http-01 --email your@email.address -d examplehome.duckdns.org
```
Once the program has run it will generate a certificate and other files and place them in a folder `/etc/letsencrypt/` .
Confirm this file has been populated:
```bash
ls /etc/letsencrypt/live/
```
This should show a folder named exactly after your DuckDNS URL.
Our Home Assistant user needs access to files within the letsencrypt folder, so issue the following commands to change the permissions.
```bash
sudo chmod 755 /etc/letsencrypt/live/
sudo chmod 755 /etc/letsencrypt/archive/
sudo chmod -R 777 /etc/letsencrypt/
```
Did all of that go without a hitch? Wahoo! Your Let's Encrypt certificate is now ready to be used with Home Assistant. Move to step 5 to put it all together
### 5 - Check the incoming connection
<div class='note'>
Following on from Step 4 your SSH will still be in the certbot folder. If you edit your configuration files over SSH you will need to change to our `homeassistant` folder:
```bash
cd ~/.homeassistant
```
If you use Samba shares to edit your files you can exit your SSH now.
</div>
If during step 4 you had to use port 443 instead of port 80 to generate your certificate, you should delete that rule now.
Go to your router's configuration pages and set up a new port forwarding rule, thus:
```text
Service name - ha_ssl
Port Range - 443
Local IP - YOUR-HA-IP
Local Port - 8123
Protocol - Both
```
Remember to save the rule changes.
Now edit your `configuration.yaml` file to reflect the SSL entries and your base URL (changing the `examplehome` subdomain to yours in all three places):
```yaml
http:
ssl_certificate: /etc/letsencrypt/live/examplehome.duckdns.org/fullchain.pem
ssl_key: /etc/letsencrypt/live/examplehome.duckdns.org/privkey.pem
```
Go to the Home Assistant UI -> **Configuration** -> **General** and set the external URL to your new URL, for example: `https://examplehome.duckdns.org`. Please note, advanced mode on your user profile must be enabled in order to see the external URL option.
You may wish to set up other options for the [HTTP](/integrations/http/) integration at this point, these extra options are beyond the scope of this guide.
Save the changes to `configuration.yaml`. Restart Home Assistant.
In step 3 we accessed our Home Assistant from the outside world with our DuckDNS URL and our port number. We are going to use a slightly different URL this time.
```text
https://examplehome.duckdns.org
```
Note the **S** after http, and that no port number is added. This is because HTTPS will use port 443 automatically, and we have already set up our port forward to redirect this request to our Home Assistant instance on port 8123.
You should now be able to see your Home Assistant instance via your DuckDNS URL, and importantly note that your browser shows the connection as secure.
You will now NO LONGER be able to access your Home Assistant via your old internal IP address in the way you previously have. Your default way to access your Home Assistant instance, even from inside your house, is to use your DuckDNS URL.
In cases where you need to access via the local network only (which should be few and far between) you can access it with the following URL (note the added **S** after http):
```text
https://YOUR-HA-IP:8123
```
...and accepting the browsers warning that you are connecting to an insecure site. This warning occurs because your certificate expects your incoming connection to come via your DuckDNS URL. It does not mean that your device has suddenly become insecure.
Some cases such as this are where your router does not allow 'loopback' or where there is a problem with incoming connections due to technical failure. In these cases you can still use your internal connection and safely ignore the warnings.
If you were previously using a webapp on your phone/tablet to access your Home Assistant you should delete the old one and create a new one with the new address. The old one will no longer work as it is not keyed to your new, secure URL.
All done? Accessing your Home Assistant from across the world with your DuckDNS URL and a lovely secure logo on your browser? Ace! Now let's clean up our port forwards so that we are only exposing the parts of our network that are absolutely necessary to the outside world.
### 6 - Clean up port forwards
In step 2 we created a port forwarding rule called `ha_test`. This opens port 8123 to the world, and is no longer necessary.
Go to your router's configuration pages and delete the `ha_test` rule.
You should now have two rules in relation to Home Assistant for your port forwards, named:
`ha_ssl` and `ha_letsencrypt`
If you have any more for Home Assistant you should delete them now. If you only have `ha_ssl` this is probably because during step 4 you had to use port 443 instead of port 80, so we deleted the rule during step 5.
You are now part of one of two groups:
- If you have BOTH rules you are able to set up auto renewals of your certificates using port 80 and the standard HTTP challenge, as performed above.
- If you only have one, you are still able to set up auto renewals of your certificates, but will have to specify additional options when renewing that will temporarily stop Home Assistant and use port 8123 for certificate renewal.
Please remember whether you are a ONE-RULE person or a BOTH-RULE person for step 8!
Let's Encrypt certificates only last for 90 days. When they have less than 30 days left they can be renewed. Renewal is a simple process.
Move on to step 7 to see how to monitor your certificates expiry date, and be ready to renew your certificate when the time comes.
### 7 - Set up a sensor to monitor the expiry date of the certificate
Setting a sensor to read the number of days left on your TLS/SSL certificate before it expires is not required, but it has the following advantages:
- You can physically see how long you have left, pleasing your inner control freak
- You can set automations based on the number of days left
- You can set alerts to notify you if your certificate has not been renewed and is coming close to expiry.
- If you cannot set up automatic renewals due to your ISP blocking port 80, you will have timely reminders to complete the process manually.
If you do not wish to set up a sensor you can skip straight to step 8 to learn how to update your certificates.
The sensor will rely on a command line program that needs to be installed on your device running Home Assistant. SSH in to the device and run the following commands:
```bash
sudo apt-get update
sudo apt-get install ssl-cert-check
```
<div class='note'>
In cases where, for whatever reason, apt-get installing is not appropriate for your installation you can fetch the ssl-cert-check script from `http://prefetch.net/code/ssl-cert-check` bearing in mind that you will have to modify the command in the sensor code below to run the script from wherever you put it, modify permission if necessary and so on.
</div>
To set up a senor add the following to your `configuration.yaml` (remembering to correct the URL for your DuckDNS):
```yaml
sensor:
- platform: command_line
name: SSL cert expiry
unit_of_measurement: days
scan_interval: 10800
command: "ssl-cert-check -b -c /etc/letsencrypt/live/examplehome.duckdns.org/cert.pem | awk '{ print $NF }'"
```
Save the `configuration.yaml`. Restart Home Assistant.
On your default_view you should now see a sensor badge containing your number of days until expiry. If you've been following this guide from the start and have not taken any breaks in between, this should be 89 or 90. The sensor will update every 3 hours. You can place this reading on a card using groups, or hide it using customize. These topics are outside of the scope of this guide, but information can be found on their respective integrations pages: [Group](/integrations/group/) and [Customize](/docs/configuration/customizing-devices/)
Got your sensor up and running and where you want it? Top drawer! Nearly there, now move on to the final steps to ensure that you're never without a secure connection in the future.
### 8 - Set up an automatic renewal of the TLS/SSL certificate
The certbot program we downloaded in step 4 contains a script that will renew your certificate. The script will only obtain a new certificate if the current one has less than 30 days left on it, so running the script more often than is actually needed will not cause any harm.
If you are a ONE-RULE person (from step 6), you can automatically renew your certificate with your current port mapping by temporarily stopping Home Assistant and telling certbot to bind port 8123 internally, and using a `tls-sni` challenge so that the Let's Encrypt CA binds port 443 externally. The flags used to specify these additional steps are shown below.
If you are a TWO-RULE person (from step 6), you can automatically renew your certificate using a `http-01` challenge and port 80.
There are a number of options for automating the renewal process:
#### Option 1
Your certificate can be renewed as a 'cron job' - cron jobs are background tasks run by the computer at specified intervals (and are totally independent of Home Assistant). Defining cron is outside of the scope of this guide but you will have had dealings with `crontab` when setting up DuckDNS in step 3
To set a cron job to run the script at regular intervals:
- SSH in to your device running Home Assistant.
- Change to your Home Assistant user (where `homeassistant` is the name of the user):
```bash
sudo -u homeassistant -H -s
```
- Open the crontab:
```bash
crontab -e
```
- If you are a TWO-RULE Person: Scroll to the bottom of the file and paste in the following line
```text
30 2 * * 1 certbot renew --quiet --no-self-upgrade --standalone --preferred-challenges http-01
```
- If you are a ONE-RULE Person: Scroll to the bottom of the file and paste in the following line
```text
30 2 * * 1 certbot renew --quiet --no-self-upgrade --standalone --preferred-challenges tls-sni-01 --tls-sni-01-port 8123 --pre-hook "sudo systemctl stop home-assistant@homeassistant.service" --post-hook "sudo systemctl start home-assistant@homeassistant.service"
```
- Let's take a moment to look at the differences here:
1. This method uses a `tls-sni` challenge, so the Let's Encrypt CA will attempt to bind port 443 externally (which you have forwarded)
2. `--tls-sni-01-port 8123` tells certbot to bind port 8123 internally, which matches with the port forwarding rules that are already in place.
3. We define pre-hooks and post-hooks that stop our Home Assistant service before certbot runs, freeing port 8123 for certificate renewal, and restart Home Assistant after renewal is complete.
- Save the file and exit
#### Option 2
You can set an automation in Home Assistant to run the certbot renewal script.
Add the following sections to your `configuration.yaml` if you are a TWO-RULE person
```yaml
shell_command:
renew_ssl: certbot renew --quiet --no-self-upgrade --standalone --preferred-challenges http-01
automation:
- alias: 'Auto Renew SSL Cert'
trigger:
platform: numeric_state
entity_id: sensor.ssl_cert_expiry
below: 29
action:
service: shell_command.renew_ssl
```
If you are a ONE-RULE person, replace the `certbot` command above with `certbot renew --quiet --no-self-upgrade --standalone --preferred-challenges tls-sni-01 --tls-sni-01-port 8123 --pre-hook "sudo systemctl stop home-assistant@homeassistant.service" --post-hook "sudo systemctl start home-assistant@homeassistant.service"`
#### Option 3
You can manually update the certificate when your certificate is less than 30 days to expiry.
To manually update:
- SSH in to your device running Home Assistant.
- Change to your Home Assistant user (where `homeassistant` is the name of the user):
```bash
sudo -u homeassistant -H -s
```
- Change to your certbot folder
```bash
cd ~/certbot/
```
- Run the renewal command
```bash
certbot renew --quiet --no-self-upgrade --standalone --preferred-challenges http-01
```
- If you are a ONE-RULE person, replace the `certbot` command above with `certbot renew --quiet --no-self-upgrade --standalone --preferred-challenges tls-sni-01 --tls-sni-01-port 8123 --pre-hook "sudo systemctl stop home-assistant@homeassistant.service" --post-hook "sudo systemctl start home-assistant@homeassistant.service"`
So, now were all set up. We have our secured, remotely accessible Home Assistant instance and we're on track for keeping our certificates up to date. But what if something goes wrong? What if the automation didn't fire? What if the cron job forgot to run? What if the dog ate my homework? Read on to set up an alert so you can be notified in plenty of time if you need to step in and sort out any failures.
### 9 - Set up an alert to warn us if something went wrong
We set up our automatic renewal of our certificates and whatever method we used the certificate should be renewed on or around 30 days before it expires. But what if a week later it still hasn't been? This alert will go off if the expiry time on the certificate gets down to 21 days. This will give you 3 weeks to fix the problem, get your new certificate installed and get another 90 days of secure Home Assistant connections in play.
In your `configuration.yaml` add the following automation, adding your preferred notification platform where appropriate:
```yaml
automation:
- alias: 'SSL expiry notification'
trigger:
platform: numeric_state
entity_id: sensor.ssl_cert_expiry
below: 21
action:
service: notify.[your_notification_preference]
data:
message: 'Warning - SSL certificate expires in 21 days and has not been automatically renewed'
```
If you receive this warning notification, follow the steps for a manual update from step 8. Any error messages received at that point can be googled and resolved. If the manual update goes without a hitch there may be something wrong with your chosen method for automatic updates, and you can start troubleshooting from there.
So, that's it. We've taken a Home Assistant instance that was only reachable on the local network, made it accessible from the internet, secured it, and set up a system to ensure that it always stays secure. Well done, go and treat yourself to a cookie!

64
source/_docs/ecosystem/certificates/tls_domain_certificate.markdown
View File

@ -1,64 +0,0 @@
---
title: "Certificate for SSL/TLS via domain ownership"
description: "Configure a certificate to use with Home Assistant"
redirect_from: /cookbook/tls_domain_certificate/
---
If your Home Assistant instance is only accessible from your local network you can still protect the communication between your browsers and the frontend with SSL/TLS. You can use [Self-sign certificate](/cookbook/tls_self_signed_certificate/) but your browser will present a warning and some https-only features might not work.
### Requirement for this guide
* Your Home Assistant instance is not exposed to the internet. If it is - use [this guide]({{site_root}}/blog/2015/12/13/setup-encryption-using-lets-encrypt/)
* You control a public domain name. The domain doesn't have to point to a site. A domain controlled by a *trusted* friend will do. (A friend you trust not to MITM you)
* Your home router supports custom DNS entries.
### Run certbot
```bash
mkdir certbot
cd certbot
wget https://dl.eff.org/certbot-auto
chmod a+x certbot-auto
sudo ./certbot-auto --manual certonly --preferred-challenges dns -d "mydomain.com" --email your@email.address
```
* Agree to Terms of Service
* Choose whether to share your email with Electronic Frontier Foundation.
* Agree to your IP being logged
You will get the following text:
```text
Please deploy a DNS TXT record under the name
_acme-challenge.mydomain.com with the following value:
deadbeefdeadbeefdeadbeefdeadbeefdeadbeef
Once this is deployed,
-------------------------------------------------------------------------------
Press Enter to Continue
```
* Deploy the value to TXT field using your domain registrar.
* Go to a site that queries domain record. For example [this one](https://mxtoolbox.com/TXTLookup.aspx) and look if it sees your brand new TXT field (Don't forget to enter the full domain: `_acme-challenge.mydomain.com`)
* Press Enter at certbot prompt.
### Make mydomain.com point to your Home Assistant instance
If your router uses DNSMasq (for example DDWRT) add the following line to DNSMasq options:
```text
address=/mydomain.com/<hass IP>
```
### Edit your Home Assistant configuration to use your certificates
The [`http`](/integrations/http/) section must contain the full path to the needed files.
```yaml
http:
ssl_certificate: /etc/letsencrypt/live/mydomain.com/fullchain.pem
ssl_key: /etc/letsencrypt/live/mydomain.com/privkey.pem
```
Make sure the files are accessible by the user that runs Home Assistant.

100
source/_docs/ecosystem/certificates/tls_self_signed_certificate.markdown
View File

@ -1,100 +0,0 @@
---
title: "Certificate Authority and self-signed certificate for SSL/TLS"
description: "Configure a Certificate Authority and self-signed certificate to use with Home Assistant"
redirect_from: /cookbook/tls_self_signed_certificate/
---
If your Home Assistant instance is only accessible from your local network, you can still protect the communication between your browsers and the frontend with SSL/TLS.
[Let's Encrypt](/blog/2017/09/27/effortless-encryption-with-lets-encrypt-and-duckdns/) will only work if you have a DNS entry and remote access is allowed.
The solution is to use a self-signed certificate. Please note, however, that after you have completed these steps, your browser will complain about the security of the certificate as it was not issued by a trusted authority.
* This is due to self-signed certificates having not been issued by a certification authority ([`CA`](https://cheapsslsecurity.com/blog/what-is-a-certificate-authority-ca/)). If you have your own CA, then this will not be an issue.
* A fantastic workaround for this, while keeping your instance isolated securely off the Internet, is to use a [`Certificate for SSL/TLS via domain ownership`](/docs/ecosystem/certificates/tls_domain_certificate/).
If you don't mind the browser warnings and simply want SSL/TLS encryption and therefore have decided to use a self-signed certificate permanently or temporarily, read on!
If you use Chrome browser version 58 or above and/or **don't want to have issues regarding a non-trusted CA or CN (Common Name)**, follow this full tutorial: [Create Root Certificate Authority and self-signed certificate for your Home Assistant. Compatible with Chrome browser > version 58](https://gist.github.com/tiagofreire-pt/4920be8d03a3dfa8201c6afedd00305e). Otherwise, follow this:
To create a certificate locally, you need the [OpenSSL](https://www.openssl.org/) command-line tool.
Change to your Home Assistant [configuration directory](/getting-started/configuration/) like `~/.homeassistant`. This will make it easier to backup your certificate and the key. Run the command shown below.
The certificate **must** be `.pem` extension.
```bash
openssl req -sha256 -addext "subjectAltName = IP:X.X.X.X" -newkey rsa:4096 -nodes -keyout privkey.pem -x509 -days 730 -out fullchain.pem
```
Where the `X.X.X.X` must be replaced with the IP address of your local machine running Home Assistant (e.g., `192.168.1.20`).
For details about the parameters, please check the OpenSSL documentation. Provide the requested information during the generation process.
At the end you will have two files called `privkey.pem` and `fullchain.pem`. The key and the certificate.
Update the `http:` entry in your `configuration.yaml` file and let it point to your created files.
Hass.io:
```yaml
http:
ssl_certificate: /ssl/fullchain.pem
ssl_key: /ssl/privkey.pem
```
Non-Hass.io:
```yaml
http:
ssl_certificate: /home/your_user/.homeassistant/fullchain.pem
ssl_key: /home/your_user/.homeassistant/privkey.pem
```
Docker:
```yaml
http:
ssl_certificate: /config/fullchain.pem
ssl_key: /config/privkey.pem
```
A restart of Home Assistant is required for the new certificate to take effect.
If you get any log error about *ssl_key* or *ssl_certificate* that is **not a file for dictionary value** when run Home Assistant, you need to change owner or access permission of the `.pem` files as following:
Home Assistant (through console or SSH add-on):
```bash
chown root:root fullchain.pem privkey.pem
chmod 600 fullchain.pem privkey.pem
```
Non-hass-io:
```bash
sudo chown homeassistant:homeassistant fullchain.pem privkey.pem
sudo chmod 600 fullchain.pem privkey.pem
```
A tutorial "[Working with SSL Certificates, Private Keys and CSRs](https://www.digitalocean.com/community/tutorials/openssl-essentials-working-with-ssl-certificates-private-keys-and-csrs)" could give you some insight about special cases.
## iOS and macOS Specific Requirements
### iOS
If you are going to use this certificate with the iOS app, you need to ensure you complete **all** fields during the certificate creation process, then:
* Send **only** the `fullchain.pem` file to the iOS device, using airdrop or other transfer method.
* Open the `.pem` file on the iOS device, follow the prompts to trust and install it.
* If you are using iOS 10.3 or newer then [additional steps](https://support.apple.com/en-us/HT204477) are needed.
### iOS 13 and macOS 10.15
There are [new security requirements](https://support.apple.com/en-us/HT210176) for TLS server certificates in iOS 13 and macOS 10.15. To summarize:
* The key size must be greater than or equal to 2048 bits.
* A hash algorithm from the SHA-2 family is required. SHA-1 signed certificates are no longer trusted for TLS.
* The DNS name of the server must be included in the Subject Alternative Name extension of the certificate.
* For certificates issued after July 1, 2019:
* Certificates must contain an ExtendedKeyUsage (EKU) extension containing the id-kp-serverAuth OID.
* Certificates must have a validity period of 825 days or fewer.

111
source/_docs/ecosystem/haproxy.markdown
View File

@ -1,111 +0,0 @@
---
title: "HAProxy"
description: "Documentation about setting up Home Assistant with HAProxy"
---
Using HAProxy to proxy for Home Assistant allows you to serve Home Assistant securely over standard ports with HTTP to HTTPS redirection.
### Install HAProxy on your server
This will vary depending on your OS. Check out Google for this.
### Obtain an SSL certificate
There are multiple ways of obtaining an SSL certificate. Let’s Encrypt is one method.
Use Google for this, but a good example of using Certbot can be found [here](https://www.digitalocean.com/community/tutorials/how-to-secure-haproxy-with-let-s-encrypt-on-ubuntu-14-04).
### HAPRoxy Configuration
The following configuration updates HAProxy defaults for more secure ciphers for SSL and logging and connection
timeouts.
Items to update for your deployment:
* `bind`: Update the ports HAProxy listens on for forwarding.
* `subdomain.domain.com`: Your domain to use
* `ssl crt`: The path to your SSL certificate.
* `server hass 127.0.0.1:8123`: The IP and port location of your Home Assistant instance.
```text
global
log /dev/log local0
log /dev/log local1 notice
chroot /var/lib/haproxy
stats socket /run/haproxy/admin.sock mode 660 level admin
stats timeout 30s
user haproxy
group haproxy
daemon
# Default SSL material locations
ca-base /etc/ssl/certs
crt-base /etc/ssl/private
# Default ciphers to use on SSL-enabled listening sockets.
# For more information, see ciphers(1SSL). This list is from:
# https://hynek.me/articles/hardening-your-web-servers-ssl-ciphers/
ssl-default-bind-ciphers ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:ECDH+3DES:DH+3DES:RSA+AESGCM:RSA+AES:RSA+3DES:!aNULL:!MD5:!DSS
ssl-default-bind-options no-sslv3
maxconn 2048
tune.ssl.default-dh-param 2048
defaults
log global
mode http
option httplog
option dontlognull
timeout connect 5000
timeout client 50000
timeout server 50000
timeout tunnel 60000 # long enough for websocket pings every 55 seconds
timeout http-request 5s # protection from Slowloris attacks
frontend www-http
bind *:80
redirect scheme https
frontend www-https
log /dev/log local0 debug
bind *:443 ssl crt /etc/haproxy/certs/MYCERT.pem
acl hass-acl hdr(host) -i SUBDOMAIN.DOMAIN.COM
use_backend hass-backend if hass-acl
backend hass-backend
server hass <Home Assistant Server IP>:8123
mode http
option forwardfor
http-request add-header X-Forwarded-Proto https
http-request add-header X-Forwarded-Port 443
```
### Forward Ports
Forward ports 443 and (optionally) 80 to your server on your router.
Do not forward port 8123, HAProxy takes care of securing the connection with HTTPS on 443.
If 8123 is forwarded then it will not be secured.
Replace 443 with whatever port you chose to bind to in the configuration if different.
### Configure Home Assistant HTTP Component
In your `configuration.yaml` file, edit the [HTTP component](/integrations/http/).
```text
http:
# For extra security set this to only accept connection on localhost if HAProxy is on the same machine
# server_host: 127.0.0.1
use_x_forwarded_for: true
# You must set the trusted proxy IP address so that Home Assistant will properly accept connections
# Set this to your HAProxy machine IP, or localhost if hosted on the same machine.
trusted_proxies: <HAProxy IP address here, 127.0.0.1 if same machine>
```
Go to the Home Assistant UI -> **Configuration** -> **General** and set the external URL
to your new URL, for example: `https://examplehome.duckdns.org`.
Please note, advanced mode on your user profile must be enabled in order to see the external URL option.
### Restart or Reload HAProxy
Use your OS method of restarting or reloading HAProxy. Use Google for this.

153
source/_docs/ecosystem/nginx.markdown
View File

@ -1,153 +0,0 @@
---
title: "NGINX"
description: "Documentation about setting up Home Assistant with NGINX."
redirect_from: /ecosystem/nginx/
---
Using NGINX as a proxy for Home Assistant allows you to serve Home Assistant securely over standard ports. This configuration file and instructions will walk you through setting up Home Assistant over a secure connection.
### 1. Get a domain name forwarded to your IP
Chances are, you have a dynamic IP address (your ISP changes your address periodically). If this is true, you can use a Dynamic DNS service to obtain a domain and set it up to update with you IP. If you purchase your own domain name, you will be able to easily get a trusted SSL certificate later.
### 2 Install NGINX on your server
This will vary depending on your OS. Check out Google for this. After installing, ensure that NGINX is not running.
<div class='note'>
You will at least need nginx >= 1.3.13, as WebSocket support is required for the reverse proxy.
</div>
### 3. Obtain an SSL certificate
There are two ways of obtaining an SSL certificate.
#### Using Let's Encrypt
If you purchased your own domain, you can use <https://letsencrypt.org> to obtain a free, publicly trusted SSL certificate. This will allow you to work with services like IFTTT. Download and install per the instructions online and get a certificate using the following command.
```bash
$ sudo ./letsencrypt-auto certonly --standalone -d example.com -d www.example.com
```
Instead of example.com, use your domain. You will need to renew this certificate every 90 days.
#### Using openssl
If you do not own your own domain, you may generate a self-signed certificate. This will not work with IFTTT, but it will encrypt all of your Home Assistant traffic.
```bash
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 9999
openssl rsa -in key.pem -out key.pem
sudo cp key.pem cert.pem /etc/nginx/ssl
sudo chmod 600 /etc/nginx/ssl/key.pem /etc/nginx/ssl/cert.pem
sudo chown root:root /etc/nginx/ssl/key.pem /etc/nginx/ssl/cert.pem
```
### 4. Create dhparams file
As a fair warning, this file will take a while to generate.
```bash
cd /etc/nginx/ssl
sudo openssl dhparam -out dhparams.pem 2048
```
### 5. Install configuration file in NGINX
Create a new file `/etc/nginx/sites-available/hass` and copy the configuration file at the bottom of the page into it.
<div class='note'>
Some Linux distributions (including CentOS and Fedora) will not have the `/etc/nginx/sites-available/` directory. In this case, remove the default server {} block from the `/etc/nginx/nginx.conf` file and paste the contents from the bottom of the page in its place. If doing this, proceed to step 7.
</div>
### 6. Enable the Home Assistant configuration
```bash
cd /etc/nginx/sites-enabled
sudo unlink default
sudo ln ../sites-available/hass default
```
### 7. Start NGINX
Double check this configuration to ensure all settings are correct and start NGINX.
### 8. Port forwarding
Forward ports 443 and 80 to your server on your router. Do not forward port 8123.
### 9. Configure Home Assistant
Home Assistant is still available without using the NGINX proxy. Restricting it to only listen to `127.0.0.1` will forbid direct accesses. Also, Home Assistant should be told to trust headers coming from the NGINX proxy only. Otherwise, incoming requests will always come from `127.0.0.1` and not the real IP address.
On your `configuration.yaml` file, edit the `http` component.
```yaml
http:
# For extra security set this to only accept connections on localhost if NGINX is on the same machine
# server_host: 127.0.0.1
use_x_forwarded_for: true
# You must set the trusted proxy IP address so that Home Assistant will properly accept connections
# Set this to your NGINX machine IP, or localhost if hosted on the same machine.
trusted_proxies: <NGINX IP address here, or 127.0.0.1 if hosted on the same machine>
```
Go to the Home Assistant UI -> **Configuration** -> **General** and set the external URL to your new URL, for example: `https://examplehome.duckdns.org`. Please note, advanced mode on your user profile must be enabled in order to see the external URL option.
### NGINX configuration
```nginx
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
# Update this line to be your domain
server_name example.com;
# These shouldn't need to be changed
listen [::]:80 default_server ipv6only=off;
return 301 https://$host$request_uri;
}
server {
# Update this line to be your domain
server_name example.com;
# Ensure these lines point to your SSL certificate and key
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
# Use these lines instead if you created a self-signed certificate
# ssl_certificate /etc/nginx/ssl/cert.pem;
# ssl_certificate_key /etc/nginx/ssl/key.pem;
# Ensure this line points to your dhparams file
ssl_dhparam /etc/nginx/ssl/dhparams.pem;
# These shouldn't need to be changed
listen [::]:443 ssl default_server ipv6only=off; # if your nginx version is >= 1.9.5 you can also add the "http2" flag here
add_header Strict-Transport-Security "max-age=31536000; includeSubdomains";
# ssl on; # Uncomment if you are using nginx < 1.15.0
ssl_protocols TLSv1.2;
ssl_ciphers "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH:!aNULL:!eNULL:!EXPORT:!DES:!MD5:!PSK:!RC4";
ssl_prefer_server_ciphers on;
ssl_session_cache shared:SSL:10m;
proxy_buffering off;
location / {
proxy_pass http://127.0.0.1:8123;
proxy_set_header Host $host;
proxy_redirect http:// https://;
proxy_http_version 1.1;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
}
}
```

118
source/_docs/ecosystem/nginx_subdomain.markdown
View File

@ -1,118 +0,0 @@
---
title: "NGINX Configuration"
description: "Configure Nginx to work with Home Assistant as a subdomain"
---
This example demonstrates how you can configure NGINX to act as a proxy for Home Assistant.
This is useful if you want to have:
* a subdomain redirecting to your Home Assistant instance
* several subdomain for several instance
* HTTPS redirection
#### Subdomain
So you already have a working NGINX server available at example.org. Your Home Assistant is correctly working on this web server and available at `http://localhost:8123`
To be able to access to your Home Assistant instance by using `https://home.example.org`, create file `/etc/nginx/sites-enabled/homeassistant` (or symlink via `/etc/nginx/sites-available`) and add the following:
```nginx
server {
listen 443 ssl;
server_name home.example.org;
ssl on;
ssl_certificate /etc/nginx/ssl/home.example.org/home.example.org-bundle.crt;
ssl_certificate_key /etc/nginx/ssl/home.example.org/home.example.org.key;
ssl_prefer_server_ciphers on;
location / {
proxy_pass http://localhost:8123;
proxy_set_header Host $host;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
location /api/websocket {
proxy_pass http://localhost:8123/api/websocket;
proxy_set_header Host $host;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}
```
If you don't want HTTPS, you can change `listen 443 ssl` to `listen 80` or better, consider redirecting all HTTP to HTTPS. See further down.
#### Multiple Instance
You already have Home Assistant running on `http://localhost:8123` and available at home.example.org as describe before. The configuration file for this Home Assistant is available in `/home/alice/.homeassistant/configuration.yaml`.
You want another instance available at `https://countryside.example.org`
You can either :
* Create a new user, `bob`, to hold the configuration file in `/home/bob/.homeassistant/configuration.yaml` and run Home Assistant as this new user
* Create another configuration directory in `/home/alice/.homeassistant2/configuration.yaml` and run Home Assistant using `hass --config /home/alice/.homeassistant2/`
In both solution, change port number used by modifying `configuration.yaml` file.
```yaml
http:
server_port: 8124
...
```
Start Home Assistant: Now, you have another instance running on `http://localhost:8124`
To access this instance by using `https://countryside.example.org` create the file `/etc/nginx/sites-enabled/countryside.example.org` (or symlink via `/etc/nginx/sites-available`) and add the following:
```nginx
server {
listen 443 ssl;
server_name countryside.example.org;
ssl on;
ssl_certificate /etc/nginx/ssl/countryside.example.org/countryside.example.org-bundle.crt;
ssl_certificate_key /etc/nginx/ssl/countryside.example.org/countryside.example.org.key;
ssl_prefer_server_ciphers on;
location / {
proxy_pass http://localhost:8124;
proxy_set_header Host $host;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
location /api/websocket {
proxy_pass http://localhost:8124/api/websocket;
proxy_set_header Host $host;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}
```
#### HTTP to HTTPS redirection
Add to your `/etc/nginx/sites-enabled/default`
```nginx
server {
listen 80 default_server;
server_name example.tld;
return 301 https://$host$request_uri;
}
```

13
source/_docs/ecosystem/notebooks.markdown
View File

@ -1,13 +0,0 @@
---
title: "Jupyter Notebooks"
description: "Jupyter Notebooks to interact offline and online with Home Assistant."
redirect_from: /ecosystem/notebooks/
---
[Jupyter Notebooks](http://jupyter.org/) allow you to create and share documents that contain live code, equations, visualizations, and explanatory text directly in your browser. Over 40 programming languages are supported including Python, R and Julia. Visit [https://try.jupyter.org/](https://try.jupyter.org/) to try out Jupyter notebooks without installing anything.
<p class='img'>
<img src='{{site_root}}/images/screenshots/jupyter-new.png' />
</p>
[nbviewer](http://nbviewer.jupyter.org/github/home-assistant/home-assistant-notebooks/tree/master/) is used to render the Home Assistant notebooks online. GitHub will also display a preview of Jupyter notebooks.

49
source/_docs/ecosystem/synology.markdown
View File

@ -1,49 +0,0 @@
---
title: "Synology"
description: "Instructions on how to get Home Assistant up and running on Synology"
redirect_from: /ecosystem/synology/
---
Synology NAS are the perfect companion to running Home Assistant. But by default, the DSM Reverse Proxy does not configure its NGINX settings to allow WebSocket, and some extra configuration will be required to get the Home Assistant frontend working with the DSM.
### Setup headers
Starting with DSM 6.2.1+, you can create "custom headers" in the Application Portal:
* Go to Application Portal and edit your entry
* Click on "custom headers" tab and click the dropdon on the "Create" button
* Select "Websocket". This will automatically add the required headers for websocket to this reverse proxy.
* Click "OK". Home Assistant should work now with the reverse proxy.
It's not necessary anymore to change the template anymore since Version DSM 6.2.1. Changing the `Portal.mustache` is not recommended! You should use the following part only if you're using a Version before DSM 6.2.1. on your Synology.
### Template change
To allow WebSocket by default for all service exposed by NGINX, you can enable it in the template file located in `/usr/syno/share/nginx/Portal.mustache`. Please be really careful in editing this file since you may break access to the DSM UI. Please backup this file before any edition.
Open `/usr/syno/share/nginx/Portal.mustache` and add the followings in the `Location` section:
```text
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 86400;
```
Then restart the NGINX daemon:
```bash
sudo synoservicecfg --restart nginx
```
This will restart the running HTTP service, not only reverse proxy, as a single instance of NGINX runs everything.
You can find more information [here](https://github.com/orobardet/dsm-reverse-proxy-websocket).
#### HTTP Configuration
- Copy the Home Assistant specific Reverse Proxy settings from the existing `/etc/nginx/app.d/server.ReverseProxy.conf` file to `/usr/local/etc/nginx/conf.d/http.HomeAssistant.conf`.
- Include these lines in the location declaration:
```text
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
```

96
source/_docs/ecosystem/tor.markdown
View File

@ -1,96 +0,0 @@
---
title: "Tor Onion Service Configuration"
description: "Configure Tor to work with Home Assistant to provide secure remote access without opening your firewall"
redirect_from: /cookbook/tor_configuration/
---
This article guides your through the configuration of Tor to provide a secure access to your Home Assistant instance as an Onion site, through [Tor's Hidden Service](https://www.torproject.org/docs/hidden-services.html.en) feature, from remote. With this enabled, you do not need to open your firewall ports or setup HTTPS to enable secure remote access.
This is useful if you want to have:
* Access your Home Assistant instance remotely without opening a firewall port or setting up a VPN.
* Don't want to or know how to get an SSL/TLS certificate and HTTPS configuration setup.
* Want to block attackers from even being able to access/scan your port and server at all.
* Want to block anyone from knowing your home IP address and seeing your traffic to your Home Assistant.
## Hidden Services and Onion Sites
Tor allows clients and relays to offer hidden services. That is, you can offer a web server, SSH server, etc., without revealing your IP address to its users. In fact, because you don't use any public address, you can run a hidden service from behind your firewall. Learn more about Hidden Services on the [Tor Project website](https://www.torproject.org/docs/tor-hidden-service.html.en).
Onion sites are websites that run on a Tor Hidden Service node. "dot onion" sites are an [IETF recognized special use domain name](https://datatracker.ietf.org/doc/rfc7686/).
## Setting up Tor on your Home Assistant
First, install Tor. On a Debian-based system, you can install the package easily:
```bash
$ sudo apt-get install tor
```
You can find more instructions for downloading and installing Tor on other platforms on the [Tor Project Download Page](https://www.torproject.org/download/download.html).
Next, modify Tor's main configuration file `/etc/tor/torrc` to include the following lines:
```bash
############### This section is just for location-hidden services ###
## Once you have configured a hidden service, you can look at the
## contents of the file ".../hidden_service/hostname" for the address
## to tell people.
...
HiddenServiceDir /var/lib/tor/homeassistant/
HiddenServicePort 80 127.0.0.1:8123
HiddenServiceAuthorizeClient stealth haremote1
...
```
The "stealth" entry above ensures traffic to and from your Home Assistant instance over Tor, is hidden even from other nodes on the Tor network. The `haremote1` value is a generic client name entry that you can modify as you please.
Then, restart Tor:
```bash
$ sudo systemctl restart tor
```
Then read the new generated authentication cookie from the Tor-generated hostname file:
```bash
$ sudo more /var/lib/tor/homeassistant/hostname
```
The output of that command should look something like this, but with your own unique "dot onion" domain and authentication cookie:
```bash
abcdef1234567890.onion ABCDEF1122334455667789 # client: haremote1
```
You are now done with the Home Assistant Tor server configuration. Make sure your Home Assistant instance is running, and now you can move to client configuration.
## Tor Client Access Setup
Using this setup, you can access your Home Assistant instance over Tor from your laptop or mobile device, using Tor Browser and other software.
Add the authentication cookie to your `torrc` client configuration on your laptop or mobile device. Using the sample values from above, it would look like this:
```bash
HidServAuth abcdef1234567890.onion ABCDEF1122334455667789
```
For Tor Browser on Windows, Mac or Linux, you can find the torrc file here: `<tor browser install directory>/Browser/TorBrowser/Data/Tor/torrc`
Once you have added the entry, restart the browser, and then browse to the "dot onion" site address to connect to your Home Assistant instance.
For [Orbot: Tor on Android](https://guardianproject.info/apps/orbot), add it in **Orbot** -> **Menu** -> **Settings** to the "Torrc Custom Configuration" entry. Restart Orbot, and then use the [Orfox browser app](https://guardianproject.info/apps/orfox/), and browse to the "dot onion" site name to access your Home Assistant instance. You can also use Orbot's VPN mode, to enable Tor access from any application on your device, such as Tasker or Owntracks.
On iOS, we have not fully tested this yet, but you should be able to add custom torrc entries on [Onion Browser](https://mike.tig.as/onionbrowser/), Red Onion or TOBY browsers, all available in the iTunes App Store.
## Some More Advanced Ideas
With this configuration, only you can access your Home Assistant instance Onion site through Tor, and no one else. You can share the authentication cookie with multiple devices and users, or you can generate a unique one for each - up to you! If you have multiple, say for an industrial, business or corporate configuration, this would provide an easy way to revoke access to a specific user or device.
If you always access your Home Assistant instance via Tor, you can easily run this on an isolated "IoT" network segment at your install site, keeping your internal home network traffic separate from any potentially compromised devices (like cheap "smart" lightbulbs with backdoors!).
You could also use Tor as a means to connect your Home Assistant instance to a remote device, sensor or other service that you do not want to or connect provide a direct, open IP connection to. Again, Tor provides authenticated and confidential routing (aka "privacy and encryption") by default, without having to setup TLS/SSL or VPN. It is just important to secure IoT nodes within your network, as it is to secure remote access!
As mentioned, with Orbot on Android, you can enable a "full device" VPN mode, that allows any app you have to tunnel through Tor, even if it is not Tor or proxy aware. This means you should be able to enter your "dot onion" Onion site address into any app you want to access to your Home Assistant instance, and it should work.

47
source/_docs/installation.markdown
View File

@ -67,49 +67,6 @@ If you use these install methods, we assume that you know how to manage and admi
## Community provided guides
These guides are provided as-is. Some of these install methods are more limited than the methods above. Some integrations may not work due to limitations of the platform or because required Python packages aren't available for that platform.
Additional installation guides can be found on our [Community Forum](https://community.home-assistant.io/tags/c/community-guides/51/installation).
<div class="text-center hass-option-cards" markdown="0">
<a class='option-card' href='/docs/installation/armbian/'>
<div class='img-container'>
<img src='/images/supported_brands/armbian.png' />
</div>
<div class='title'>armbian</div>
</a>
<a class='option-card' href='/docs/installation/archlinux/'>
<div class='img-container'>
<img src='/images/supported_brands/archlinux.png' />
</div>
<div class='title'>ArchLinux</div>
</a>
<a class='option-card' href='/docs/installation/fedora/'>
<div class='img-container'>
<img src='/images/supported_brands/fedora.png' />
</div>
<div class='title'>Fedora</div>
</a>
<a class='option-card' href='/docs/installation/centos/'>
<div class='img-container'>
<img src='/images/supported_brands/centos.png' />
</div>
<div class='title'>CentOS/RHEL</div>
</a>
<a class='option-card' href='/docs/installation/macos/'>
<div class='img-container'>
<img src='https://brands.home-assistant.io/ios/icon.png' />
</div>
<div class='title'>macOS</div>
</a>
<a class='option-card' href='/docs/installation/synology/'>
<div class='img-container'>
<img src='https://brands.home-assistant.io/synology/logo.png' />
</div>
<div class='title'>Synology</div>
</a>
<a class='option-card' href='/docs/installation/freenas/'>
<div class='img-container'>
<img src='/images/supported_brands/freenas.png' />
</div>
<div class='title'>FreeNAS</div>
</a>
</div>
These Community Guides are provided as-is. Some of these install methods are more limited than the methods above. Some integrations may not work due to limitations of the platform.

16
source/_docs/installation/archlinux.markdown
View File

@ -1,16 +0,0 @@
---
title: "Installation on Arch Linux"
description: "Installation of Home Assistant on your Arch Linux computer."
---
[Arch Linux](https://www.archlinux.org/) is a lightweight and flexible Linux distribution for x86_64.
Install the needed Python packages.
```bash
sudo pacman -S python
sudo pacman -S python-pip
```
From here on, we recommend you to follow the
[virtualenv](https://www.home-assistant.io/docs/installation/virtualenv/) guide.

29
source/_docs/installation/armbian.markdown
View File

@ -1,29 +0,0 @@
---
title: "Installation on a Armbian system"
description: "Instructions to install Home Assistant on an Armbian-powered systems."
---
[armbian](https://www.armbian.com) runs on a wide-variety of [ARM development boards](https://www.armbian.com/download/). Currently there are around 50 boards supported inclusive the OrangePi family, Cubieboard, Pine64, and ODROID.
Setup Python and `pip`:
```bash
sudo apt-get update
sudo apt-get install python3-dev python3-pip libffi-dev libssl-dev
```
Now that you installed python, there are two ways to install Home Assistant:
1. It is recommended to install Home Assistant in a virtual environment to avoid using `root`, using the [VirtualEnv instructions](/docs/installation/virtualenv/)
2. Alternatively, you can install Home Assistant for the user you created when first booting Armbian:
```bash
sudo pip3 install homeassistant
hass --open-ui
```
Running these commands will:
- Install Home Assistant
- Launch Home Assistant and serve the web interface on `http://localhost:8123`
- The configuration files will be created in `/home/{user}/.homeassistant`

74
source/_docs/installation/centos.markdown
View File

@ -1,74 +0,0 @@
---
title: "Installation on CentOS/RHEL"
description: "Installation of Home Assistant on your CentOS/RHEL computer."
---
To run Python 3.x on [CentOS](https://www.centos.org/) or RHEL (Red Hat Enterprise Linux), [Software Collections](https://www.softwarecollections.org/en/scls/rhscl/rh-python36/) needs to be activated first.
### Using Software Collections
First of all install the software collection repository as root and [scl utils](https://access.redhat.com/documentation/en-US/Red_Hat_Developer_Toolset/1/html-single/Software_Collections_Guide/). For example, on CentOS:
```bash
sudo yum install centos-release-scl
sudo yum-config-manager --enable centos-sclo-rh-testing
sudo yum install -y scl-utils
```
Install some dependencies you'll need later.
```bash
sudo yum install gcc gcc-c++ systemd-devel
```
Then install the Python 3.6 package. If you are using CentOS 7 then you may have to install the packages for Python 3.6 using RHEL Methods listed here: https://www.softwarecollections.org/en/scls/rhscl/rh-python36/) for this to work as mentioned above.
```bash
sudo yum install rh-python36
```
This is part of the slight change when trying to install Python 3.6 and running the command `python36 --version` which will after install give you the correct version, but won't allow you to set the software collection using the `scl` command. This command downloads the RH collection of Python to allow you to run `scl` command to enable the environment in `bash` and then run the automate command using the template.
```bash
yum install rh-python36
```
### Start using software collections
```bash
scl enable rh-python36 bash
```
Once installed, switch to your `homeassistant` user (if you've set one up), enable the software collection and check that it has set up the new version of Python:
```bash
$ python --version
Python 3.6.3
```
You will be in a command shell set up with Python 3.6 as your default version. The `virtualenv` and `pip` commands will be correct for this version, so you can now create a virtual environment and install Home Assistant following the main [instructions](/docs/installation/virtualenv/#step-4-set-up-the-virtualenv).
You will need to enable the software collection each time you log on before you activate your virtual environment.
### Systemd with Software Collections
To autostart Home Assistant using systemd and a python36 (from SCL) virtual environment, follow the main [instructions](/docs/autostart/systemd/) and adjust the template as follows:
Filename: `/etc/systemd/system/home-assistant@homeassistant.service`
```txt
[Unit]
Description=Home Assistant
After=network-online.target
[Service]
Type=simple
# %i means the username is derrived from the filename.
User=%i
# a python venv for hass exists in /opt/hass/venv
ExecStart=/srv/homeassistant/bin/hass
[Install]
WantedBy=multi-user.target
```
This works because the Python virtual environment was created using the SCL environment, thus there is no need to activate SCL.

37
source/_docs/installation/fedora.markdown
View File

@ -1,37 +0,0 @@
---
title: "Installation on Fedora"
description: "Installation of Home Assistant on your Fedora computer."
---
[Fedora](https://fedoraproject.org) is an operating system based on the Linux kernel, developed by the community-supported Fedora Project. There are releases for x86 and x86_64 including ARM and other architectures.
Install the development package of Python.
```bash
sudo dnf -y install python3-devel redhat-rpm-config
```
To isolate the Home Assistant installation a [`venv`](https://docs.python.org/3/library/venv.html) is handy. First create a new directory to store the installation and adjust the permissions.
```bash
sudo mkdir -p /opt/homeassistant
sudo useradd -rm homeassistant -G dialout
sudo chown -R homeassistant:homeassistant /opt/homeassistant
```
Now switch to the new directory, setup the `venv`, and activate it.
```bash
sudo -u homeassistant -H -s
cd /opt/homeassistant
python3.8 -m venv .
source bin/activate
```
Install Home Assistant itself.
```bash
pip3 install homeassistant colorlog
```
Check the [autostart](/docs/autostart/systemd/) section in the documentation for further details and the [Firewall section](/docs/installation/troubleshooting/#no-access-to-the-frontend) if you want to access your Home Assistant installation.

338
source/_docs/installation/freenas.markdown
View File

@ -1,338 +0,0 @@
---
title: "Installation on FreeNAS 11.2"
description: "Installation of Home Assistant on your FreeNAS."
---
[FreeNAS](https://www.freenas.org) is a free and open-source network-attached storage (NAS) software based on FreeBSD and the OpenZFS file system. It is licensed under the terms of the BSD License and runs on commodity x86-64 hardware.
This has been tested on FreeNAS 11.2 and should also work on FreeBSD 11.x as well. These instructions assume you already have a running and accessible jail. For more information on creating a jail read the official FreeNAS User Guide regarding [Jails](https://www.ixsystems.com/documentation/freenas/11.2/jails.html). Once you have the jail available, follow the steps below. Directories used follow standard BSD conventions but can be adjusted as you wish.
Enter the Home Assistant jail. If you don't know which name you have given the jail, you can use the `iocage list` command to check.
```bash
# If the jail is called 'HomeAssistant'
iocage exec HomeAssistant
```
Install the suggested packages:
```bash
pkg update
pkg upgrade
pkg install -y autoconf bash ca_root_nss gmake pkgconf python37 py37-sqlite3
```
Create the user and group that Home Assistant will run as. The user/group ID of `8123` can be replaced if this is already in use in your environment.
```bash
pw groupadd -n homeassistant -g 8123
echo 'homeassistant:8123:8123::::::/usr/local/bin/bash:' | adduser -f -
```
Create the installation directory:
```bash
mkdir -p /usr/local/share/homeassistant
chown -R homeassistant:homeassistant /usr/local/share/homeassistant
```
Create the virtualenv and install Home Assistant itself:
```bash
su homeassistant
cd /usr/local/share/homeassistant
python3.7 -m venv .
source ./bin/activate
pip3 install --upgrade pip
pip3 install homeassistant
```
While still in the `venv`, start Home Assistant to populate the configuration directory.
```bash
hass --open-ui
```
Wait until you see:
```bash
(MainThread) [homeassistant.core] Starting Home Assistant
```
Then escape and exit the `venv`.
```bash
deactivate
exit
```
Create the directory and the `rc.d` script for the system-level service that enables Home Assistant to start when the jail starts.
```bash
mkdir /usr/local/etc/rc.d/
```
Then create a file at `/usr/local/etc/rc.d/homeassistant` and insert the content below:
```bash
vi /usr/local/etc/rc.d/homeassistant
```
```bash
#!/bin/sh
#
# Based upon work by tprelog at https://github.com/tprelog/iocage-homeassistant/blob/11.3-RELEASE/overlay/usr/local/etc/rc.d/homeassistant
#
# PROVIDE: homeassistant
# REQUIRE: LOGIN
# KEYWORD: shutdown
#
# homeassistant_user: The user account used to run the homeassistant daemon.
# This is optional, however do not specifically set this to an
# empty string as this will cause the daemon to run as root.
# Default: homeassistant
# homeassistant_group: The group account used to run the homeassistant daemon.
# This is optional, however do not specifically set this to an
# empty string as this will cause the daemon to run with group wheel.
# Default: homeassistant
#
# homeassistant_venv: Directory where homeassistant virtualenv is installed.
# Default: "/usr/local/share/homeassistant"
# Change: `sysrc homeassistant_venv="/srv/homeassistant"`
# UnChange: `sysrc -x homeassistant_venv`
#
# homeassistant_config_dir: Directory where homeassistant config is located.
# Default: "/home/homeassistant/.homeassistant"
# Change: `sysrc homeassistant_config_dir="/home/hass/homeassistant"`
# UnChange: `sysrc -x homeassistant_config_dir`
# -------------------------------------------------------
# Copy this file to '/usr/local/etc/rc.d/homeassistant'
# `chmod +x /usr/local/etc/rc.d/homeassistant`
# `sysrc homeassistant_enable=yes`
# `service homeassistant start`
# -------------------------------------------------------
. /etc/rc.subr
name=homeassistant
rcvar=${name}_enable
pidfile_child="/var/run/${name}.pid"
pidfile="/var/run/${name}_daemon.pid"
logfile="/var/log/${name}.log"
load_rc_config ${name}
: ${homeassistant_enable:="NO"}
: ${homeassistant_user:="homeassistant"}
: ${homeassistant_group:="homeassistant"}
: ${homeassistant_config_dir:="/home/homeassistant/.homeassistant"}
: ${homeassistant_venv:="/usr/local/share/homeassistant"}
command="/usr/sbin/daemon"
extra_commands="check_config restart test upgrade"
start_precmd=${name}_precmd
homeassistant_precmd() {
rc_flags="-f -o ${logfile} -P ${pidfile} -p ${pidfile_child} ${homeassistant_venv}/bin/hass --config ${homeassistant_config_dir} ${rc_flags}"
[ ! -e "${pidfile_child}" ] && install -g ${homeassistant_group} -o ${homeassistant_user} -- /dev/null "${pidfile_child}"
[ ! -e "${pidfile}" ] && install -g ${homeassistant_group} -o ${homeassistant_user} -- /dev/null "${pidfile}"
[ -e "${logfile}" ] && rm -f -- "${logfile}"
install -g ${homeassistant_group} -o ${homeassistant_user} -- /dev/null "${logfile}"
if [ ! -d "${homeassistant_config_dir}" ]; then
install -d -g ${homeassistant_group} -o ${homeassistant_user} -m 775 -- "${homeassistant_config_dir}"
fi
}
stop_postcmd=${name}_postcmd
homeassistant_postcmd() {
rm -f -- "${pidfile}"
rm -f -- "${pidfile_child}"
}
upgrade_cmd="${name}_upgrade"
homeassistant_upgrade() {
service ${name} stop
su ${homeassistant_user} -c '
source ${@}/bin/activate || exit 1
pip3 install --upgrade homeassistant
deactivate
' _ ${homeassistant_venv} || exit 1
[ $? == 0 ] && homeassistant_check_config && service ${name} start
}
check_config_cmd="${name}_check_config"
homeassistant_check_config() {
[ ! -e "${homeassistant_config_dir}/configuration.yaml" ] && return 0
echo "Performing check on Home Assistant configuration:"
#eval "${homeassistant_venv}/bin/hass --config ${homeassistant_config_dir} --script check_config"
su ${homeassistant_user} -c '
source ${1}/bin/activate || exit 2
hass --config ${2} --script check_config || exit 3
deactivate
' _ ${homeassistant_venv} ${homeassistant_config_dir}
}
restart_cmd="${name}_restart"
homeassistant_restart() {
homeassistant_check_config || exit 1
echo "Restarting Home Assistant"
service ${name} stop
service ${name} start
}
test_cmd="${name}_test"
homeassistant_test() {
echo -e "\nTesting virtualenv...\n"
[ ! -d "${homeassistant_venv}" ] && echo -e " NO DIRECTORY: ${homeassistant_venv}\n" && exit
[ ! -f "${homeassistant_venv}/bin/activate" ] && echo -e " NO FILE: ${homeassistant_venv}/bin/activate\n" && exit
## switch users / activate virtualenv / get version
su "${homeassistant_user}" -c '
source ${1}/bin/activate || exit 2
echo " $(python --version)" || exit 3
echo " Home Assistant $(pip3 show homeassistant | grep Version | cut -d" " -f2)" || exit 4
deactivate
' _ ${homeassistant_venv}
[ $? != 0 ] && echo "exit $?"
}
load_rc_config ${name}
run_rc_command "$1"
```
Make the `rc.d` script executable:
```bash
chmod +x /usr/local/etc/rc.d/homeassistant
```
Configure the service to start on boot and start the Home Assistant service:
```bash
sysrc homeassistant_enable="YES"
service homeassistant start
```
You can also restart the jail to ensure that Home Assistant starts on boot.
<div class='note'>
USB Z-Wave sticks may give `dmesg` warnings similar to "data interface 1, has no CM over data, has no break". This doesn't impact the function of the Z-Wave stick in Home Assistant. Just make sure the proper `/dev/cu*` is used in the Home Assistant `configuration.yaml` file.
</div>
## Adding support for Z-Wave stick
The following two packages need to be installed in the jail
```bash
pkg install gmake
pkg install libudev-devd
```
Then you can install the Z-Wave package
```bash
su homeassistant
cd /usr/local/share/homeassistant
source ./bin/activate.csh
pip3 install homeassistant-pyozw==0.1.7
deactivate
exit
```
Stop the Home Assistant Jail
```bash
sudo iocage stop HomeAssistant
```
Edit the devfs rules on the FreenNAS Host
```bash
vi /etc/devfs.rules
```
Add the following lines
```bash
[devfsrules_jail_allow_usb=7]
add path 'cu\*' mode 0660 group 8123 unhide
```
Reload devfs
```bash
sudo service devfs restart
```
Edit the ruleset used by the jail in the FreeNAS GUI by going to Jails -> `hass` -> Edit -> Jail Properties -> devfs_ruleset
Set it to 7
Start the Home Assistant jail
```bash
sudo iocage start HomeAssistant
```
Connect to the Home Assistant jail and verify that you see the modem devices
```bash
sudo iocage console HomeAssistant
```
```bash
ls /dev/cu*
```
This should output the following
```bash
/dev/cuau0 /dev/cuaU0
```
Add the Z-Wave configuration to your `configuration.yaml` and restart Home Assistant
```bash
vi /home/homeassistant/.homeassistant/configuration.yaml
```
```yaml
zwave:
usb_path: /dev/cuaU0
polling_interval: 10000
```
```bash
service homeassistant restart
```
## Updating
Before updating, read the changelog to see what has changed and how it affects your Home Assistant instance. Enter the jail using `iocage exec <jailname>`. Stop the Home Assistant service:
```bash
service homeassistant stop
```
Then, enter the `venv`:
```bash
su homeassistant
cd /usr/local/share/homeassistant
source ./bin/activate
```
Upgrade Home Assistant:
```bash
pip3 install homeassistant --upgrade
```
Log out of the `homeassistant` user and start Home Assistant:
```bash
exit
service homeassistant start
```

12
source/_docs/installation/hassbian.markdown
View File

@ -1,12 +0,0 @@
---
title: "Hassbian"
description: "Hassbian image for a Raspberry Pi."
redirect_from: /getting-started/hassbian/
---
<div class='note warning'>
The Hassbian image is deprecated as of October 2019. Please move to another [installation method](/getting-started/).
</div>

18
source/_docs/installation/macos.markdown
View File

@ -1,18 +0,0 @@
---
title: "Installation on macOS"
description: "Installation of Home Assistant on your macOS system."
---
[macOS](http://www.apple.com/macos/) is available by default on Apple computer. If you run a different operating system, please refer to the other section of the documentation.
To run Home Assistant on macOS, you need to install Python first. Download Python 3.7 or later from [https://www.python.org/downloads/mac-osx/](https://www.python.org/downloads/mac-osx/) and follow the instructions of the installer.
Open a terminal and install Home Assistant in a virtual environment:
```bash
python3 -m venv homeassistant
source homeassistant/bin/activate
pip3 install homeassistant
```
You can then configure Home Assistant to autostart by following [this guide](/docs/autostart/macos/).

10
source/_docs/installation/raspberry-pi-all-in-one.markdown
View File

@ -1,10 +0,0 @@
---
title: "Raspberry Pi All-In-One Installer"
redirect_from: /getting-started/installation-raspberry-pi-all-in-one/
---
<div class='note warning'>
The All-In-One Installer is deprecated, you will have problems updating Home Assistant in 2018. Please move to another [installation method](/getting-started/).
</div>

2
source/_docs/installation/raspberry-pi.markdown
View File

@ -92,8 +92,6 @@ When you run the `hass` command for the first time, it will download, install an
</div>
If you want to setup `hass` as a daemon and autostart it on boot please refer to [Autostart Home Assistant Core](/docs/autostart/).
### Updating
To update to the latest version of Home Assistant Core follow these simple steps:

243
source/_docs/installation/synology.markdown
View File

@ -1,243 +0,0 @@
---
title: "Installation on a Synology NAS"
description: "Instructions to install Home Assistant on a Synology NAS."
redirect_from: /getting-started/installation-synology/
---
<div class='note warning'>
Synology only provide Python 3.5.1, which is not compatible with Home Assistant 0.65.0 or later. Until Synology offer an updated version of Python, Home Assistant 0.64 is the most recent version that will be able to be installed. You can manually specify the version of Home Assistant to install, for example to install version 0.64.3 you would do `./python3 -m pip install homeassistant==0.64.3`
</div>
There are 3 alternatives, when using Home Assistant on Synology NAS:
1. Using Home Assistant Core on Docker
2. Directly running Home Assistant Core on DSM
3. Using the Home Assistant a VM (if you have an Intel based Synology)
Option 1 is described on the [Docker installation page](/docs/installation/docker/).
Option 3 uses the Synology Based Virtual Machine Manager. You can import the VDI image to be found at the [Home Assistant installation page](/hassio/installation/). Download the image and add it to the image store. The go to "Virtual Machine" in the interface and create a new VM with the image you just added.
The main benefit from this method is that you can assign Home Assistant its own IP number, so there is no risk regarding TCP/UDP port conflicts. USB dongles an be connected to the VM without the need to install a driver in DSM.
Option 2 is described below.
The following configuration has been tested on Synology 413j running DSM 6.0-7321 Update 1.
Running these commands will:
- Install Home Assistant
- Enable Home Assistant to be launched on `http://localhost:8123`
Using the Synology webadmin:
- Install python3 using the Synology Package Center
- Create a `homeassistant` user and add to the "users" group
SSH onto your Synology & login as admin or root
- Log in with your own administrator account
- Switch to root using:
```bash
$ sudo -i
```
Check the path to python3 (assumed to be /volume1/@appstore/py3k/usr/local/bin)
```bash
# cd /volume1/@appstore/py3k/usr/local/bin
```
Install PIP (Python's package management system)
```bash
# ./python3 -m ensurepip
```
Use PIP to install the Home Assistant package 0.64.3
```bash
# ./python3 -m pip install homeassistant==0.64.3
```
Create a Home Assistant configuration directory & switch to it
```bash
# mkdir /volume1/homeassistant
# chown homeassistant /volume1/homeassistant
# chmod 755 /volume1/homeassistant
# cd /volume1/homeassistant
```
Hint: alternatively you can also create a "Shared Folder" via Synology WebUI (e.g., via "File Station") - this has the advantage that the folder is visible via "File Station".
Create hass-daemon file using the following code (edit the variables in uppercase if necessary)
```bash
#!/bin/sh
# Package
PACKAGE="homeassistant"
DNAME="Home Assistant"
# Others
USER="homeassistant"
PYTHON_DIR="/volume1/@appstore/py3k/usr/local/bin"
PYTHON="$PYTHON_DIR/python3"
HASS="$PYTHON_DIR/hass"
INSTALL_DIR="/volume1/homeassistant"
PID_FILE="$INSTALL_DIR/home-assistant.pid"
FLAGS="-v --config $INSTALL_DIR --pid-file $PID_FILE --daemon"
REDIRECT="> $INSTALL_DIR/home-assistant.log 2>&1"
start_daemon ()
{
sudo -u ${USER} /bin/sh -c "$PYTHON $HASS $FLAGS $REDIRECT;"
}
stop_daemon ()
{
kill `cat ${PID_FILE}`
wait_for_status 1 20 || kill -9 `cat ${PID_FILE}`
rm -f ${PID_FILE}
}
daemon_status ()
{
if [ -f ${PID_FILE} ] && kill -0 `cat ${PID_FILE}` > /dev/null 2>&1; then
return
fi
rm -f ${PID_FILE}
return 1
}
wait_for_status ()
{
counter=$2
while [ ${counter} -gt 0 ]; do
daemon_status
[ $? -eq $1 ] && return
let counter=counter-1
sleep 1
done
return 1
}
case $1 in
start)
if daemon_status; then
echo ${DNAME} is already running
exit 0
else
echo Starting ${DNAME} ...
start_daemon
exit $?
fi
;;
stop)
if daemon_status; then
echo Stopping ${DNAME} ...
stop_daemon
exit $?
else
echo ${DNAME} is not running
exit 0
fi
;;
restart)
if daemon_status; then
echo Stopping ${DNAME} ...
stop_daemon
echo Starting ${DNAME} ...
start_daemon
exit $?
else
echo ${DNAME} is not running
echo Starting ${DNAME} ...
start_daemon
exit $?
fi
;;
status)
if daemon_status; then
echo ${DNAME} is running
exit 0
else
echo ${DNAME} is not running
exit 1
fi
;;
log)
echo ${LOG_FILE}
exit 0
;;
*)
exit 1
;;
esac
```
Create links to Python folders to make things easier in the future:
```bash
# ln -s /volume1/@appstore/py3k/usr/local/bin/python3 python3
# ln -s /volume1/@appstore/py3k/usr/local/lib/python3.5/site-packages/homeassistant homeassistant
```
Set the owner and permissions on your configuration folder
```bash
# chown -R homeassistant:users /volume1/homeassistant
# chmod -R 664 /volume1/homeassistant
```
Make the daemon file executable:
```bash
# chmod 755 /volume1/homeassistant/hass-daemon
```
Update your firewall (if it is turned on the Synology device):
- Go to your Synology control panel
- Go to security
- Go to firewall
- Go to Edit Rules
- Click Create
- Select Custom: Destination port "TCP"
- Type "8123" in port
- Click on OK
- Click on OK again
Copy your `configuration.yaml` file into the configuration folder
That's it... you're all set to go
Here are some useful commands:
- Start Home Assistant:
```bash
$ sudo /volume1/homeassistant/hass-daemon start
```
- Stop Home Assistant:
```bash
$ sudo /volume1/homeassistant/hass-daemon stop
```
- Restart Home Assistant:
```bash
$ sudo /volume1/homeassistant/hass-daemon restart
```
- Upgrade Home Assistant::
```bash
$ /volume1/@appstore/py3k/usr/local/bin/python3 -m pip install --upgrade homeassistant
```

16
source/_docs/installation/troubleshooting.markdown
View File

@ -33,20 +33,11 @@ On a Debian system, install the Python 3 YAML library by `sudo apt-get install p
This is a known issue if you're on a Mac using Homebrew to install Python. Please follow [these instructions](https://github.com/Homebrew/brew/blob/master/docs/Homebrew-and-Python.md#note-on-pip-install---user) to resolve it.
#### No access to the frontend
In newer Linux distributions (at least Fedora > 22/CentOS 7) the access to a host is very limited. This means that you can't access the Home Assistant frontend that is running on a host outside of the host machine. Windows and macOS machines may also have issues with this.
In newer Linux distributions the access to a host is very limited. This means that you can't access the Home Assistant frontend that is running on a host outside of the host machine.
To fix this you will need to open your machine's firewall for TCP traffic to port 8123. The method for doing this will vary depending on your operating system and the firewall you have installed. Below are some suggestions to try. Google is your friend here.
- [Windows instructions](http://windows.microsoft.com/en-us/windows/open-port-windows-firewall#1TC=windows-7)
- [macOS instructions](https://support.apple.com/en-us/HT201642)
For systems with **firewalld** (Fedora, CentOS/RHEL, etc.):
```bash
sudo firewall-cmd --permanent --add-port=8123/tcp
sudo firewall-cmd --reload
```
For UFW systems (Ubuntu, Debian, Raspbian, etc.):
```bash
@ -61,9 +52,10 @@ iptables-save > /etc/network/iptables.rules # your rules may be saved elsewhere
```
#### After upgrading, your browser login gets stuck at the "loading data" step
After upgrading to a new version, you may notice your browser gets stuck at the "loading data" login screen. Close the window/tab and go into your browser settings and delete all the cookies for your URL. You can then log back in and it should work.
Android Chrome
Android Chrome
chrome -> settings -> site settings -> storage -> search for your URL for Home Assistant-> "clear & reset"
#### Not initializing discovery because could not install dependency netdisco

3
source/_docs/installation/updating.markdown
View File

@ -36,7 +36,8 @@ For a Raspberry Pi Docker container, simply pull the latest stable one:
sudo docker pull homeassistant/raspberrypi3-homeassistant:stable
```
After updating, you must start/restart Home Assistant for the changes to take effect. This means that you will have to restart `hass` itself or the [autostarting](/docs/autostart/) daemon (if applicable). Startup can take a considerable amount of time (i.e., minutes) depending on your device. This is because all requirements are updated as well.
After updating, you must start/restart Home Assistant for the changes to take effect. This means that you will have to restart `hass` itself.
Startup can take a considerable amount of time (i.e., minutes) depending on your device. This is because all requirements are updated as well.
[BRUH automation](https://www.bruhautomation.io/) has created [a tutorial video](https://www.youtube.com/watch?v=tuG2rs1Cl2Y) explaining how to upgrade Home Assistant.

1
source/_docs/installation/virtualenv.markdown
View File

@ -98,7 +98,6 @@ pip3 install --upgrade git+git://github.com/home-assistant/home-assistant.git@de
- In the future, if you want to start Home Assistant manually again, follow step 2, 3 and 5.
- It's recommended to run Home Assistant as a dedicated user.
- If you want Home Assistant to automatically start at boot, check the [autostart documentation](/docs/autostart/)
<div class='info'>

2
source/_docs/tools/keyring.markdown
View File

@ -32,6 +32,6 @@ Please enter password for encrypted keyring:
<div class='note warning'>
If you are using the Python Keyring, [autostarting](/getting-started/autostart/) of Home Assistant will no longer work.
If you are using the Python Keyring, automatic starting of Home Assistant Core will no longer work.
</div>

73
source/_includes/asides/docs_navigation.html
View File

@ -3,7 +3,8 @@
<h1 class="title delta">Topics</h1>
<ul class="divided sidebar-menu">
<li>
<b>{% active_link /faq/ FAQ %}</b> |
<b>{% active_link /faq/ FAQ %}</b>
|
<b>{% active_link /docs/glossary/ Glossary %}</b>
</li>
<li>
@ -192,76 +193,6 @@
<li>{% active_link /docs/mqtt/processing_json/ Processing JSON %}</li>
</ul>
</li>
<li>
{% active_link /docs/ecosystem/ Ecosystem %}
<ul>
<li>
{% active_link /docs/autostart/ Autostart %}
<ul>
<li>
{% active_link /docs/autostart/systemd/ systemd (Linux) %}
</li>
<li>
{% active_link /docs/autostart/upstart/ Upstart (Linux) %}
</li>
<li>{% active_link /docs/autostart/init.d/ init.d (Linux) %}</li>
<li>{% active_link /docs/autostart/macos/ macOS %}</li>
<li>{% active_link /docs/autostart/synology/ Synology NAS %}</li>
</ul>
</li>
<li>
Remote access
<ul>
<li>{% active_link /docs/ecosystem/apache/ Apache %}</li>
<li>{% active_link /docs/ecosystem/caddy/ Caddy Server %}</li>
<li>{% active_link /docs/ecosystem/haproxy/ HAProxy %}</li>
<li>{% active_link /docs/ecosystem/nginx/ NGINX %}</li>
<li>
{% active_link /docs/ecosystem/nginx_subdomain/ NGINX with
subdomain%}
</li>
<li>{% active_link /docs/ecosystem/tor/ Tor Onion Service %}</li>
</ul>
</li>
<li>
{% active_link /docs/ecosystem/certificates/ Certificates %}
<ul>
<li>
{% active_link
/docs/ecosystem/certificates/tls_self_signed_certificate/
Self-signed certificate %}
</li>
<li>
{% active_link
/docs/ecosystem/certificates/tls_domain_certificate/ Certificate
domain owners %}
</li>
<li>
{% active_link /docs/ecosystem/certificates/lets_encrypt/ Let's
Encrypt (detailed) %}
</li>
</ul>
</li>
<li>
Backup
<ul>
<li>
{% active_link /docs/ecosystem/backup/backup_github/ Backup to
GitHub %}
</li>
<li>
{% active_link /docs/ecosystem/backup/backup_dropbox/ Backup to
Dropbox %}
</li>
<li>
{% active_link /docs/ecosystem/backup/backup_usb/ Backup to USB
device %}
</li>
</ul>
</li>
<li>{% active_link /docs/ecosystem/synology/ Synology %}</li>
</ul>
</li>
</ul>
</div>
</section>

2
source/_integrations/http.markdown
View File

@ -115,8 +115,6 @@ http:
The [Set up encryption using Let's Encrypt](/blog/2015/12/13/setup-encryption-using-lets-encrypt/) blog post gives you details about the encryption of your traffic using free certificates from [Let's Encrypt](https://letsencrypt.org/).
Or use a self signed certificate following the instructions here [Self-signed certificate for SSL/TLS](/docs/ecosystem/certificates/tls_self_signed_certificate/).
## APIs
On top of the `http` integration is a [REST API](/developers/rest_api/), [Python API](/developers/python_api/) and [WebSocket API](/developers/websocket_api/) available. There is also support for [Server-sent events](/developers/server_sent_events/).

2
source/_integrations/sensehat.markdown
View File

@ -191,6 +191,6 @@ This fix has been tested with a clean install of:
and
* [Home Assistant 0.37.1](/getting-started/installation-raspberry-pi-all-in-one/)
* Home Assistant 0.37.1
For setting up the Sense HAT's RGB LED matrix as lights within Home Assistant, please see the [Sense HAT light component](#light).

3
source/_posts/2016-05-22-get-started-with-all-in-one-installer.markdown
View File

@ -9,7 +9,7 @@ categories: Video
og_image: /images/blog/2016-05-video-all-in-one-installer/preview-video.jpg
---
We are always hard at work at the virtual Home Assistant headquarters to make it easier for you to get started with Home Assistant. That's why [@patchedsoul] recently introduced the [all-in-one installer]. It allows you to get up and running with a complete Home Assistant setup by entering one line of code into your Raspberry Pi running Raspbian Jessie:
We are always hard at work at the virtual Home Assistant headquarters to make it easier for you to get started with Home Assistant. That's why [@patchedsoul] recently introduced the all-in-one installer. It allows you to get up and running with a complete Home Assistant setup by entering one line of code into your Raspberry Pi running Raspbian Jessie:
```bash
wget -Nnv https://raw.githubusercontent.com/home-assistant/fabric-home-assistant/master/hass_rpi_installer.sh && bash hass_rpi_installer.sh;
@ -22,4 +22,3 @@ This feature wouldn't be complete if it wasn't accompanied by a new video by Ben
</div>
[@patchedsoul]: https://github.com/patchedsoul
[all-in-one installer]: /getting-started/installation-raspberry-pi-all-in-one/

3
source/_posts/2016-06-18-pandora-bt-home-hub-5-and-local-file-camera.markdown
View File

@ -10,7 +10,7 @@ categories: Release-Notes
It's time for the 0.22 release. This was a pretty rough release cycle and we had to issue two hot fixes for our core improvements. But it seems now that all is good and a lot of people have reported that their installs are faster than ever and the occasional quirks no longer occur.
We are aware that our new web stack has caused issues installing Home Assistant on ARM-based platforms. This sadly includes the Raspberry Pi and Synology NAS systems. We're working on getting to a better solution. For Raspberry Pi, the [All-in-One installer] will take care of everything for you. We're working on updating our [standalone Raspberry Pi installation guide].
We are aware that our new web stack has caused issues installing Home Assistant on ARM-based platforms. This sadly includes the Raspberry Pi and Synology NAS systems. We're working on getting to a better solution. For Raspberry Pi, the All-in-One installer will take care of everything for you. We're working on updating our [standalone Raspberry Pi installation guide].
There are two cool things that I want to highlight in this release. The first is Pandora support. This is based on the CLI player called pianobar. This means that your machine running Home Assistant can be connected to the speakers and provide your house with tunes.
@ -86,7 +86,6 @@ netatmo:
[alexa]: /integrations/alexa/#working-with-scenes
[Plex sensor]: /integrations/plex#sensor
[Swagger.yaml format]: https://github.com/home-assistant/home-assistant/blob/dev/docs/swagger.yaml
[All-in-One installer]: /getting-started/installation-raspberry-pi-all-in-one/
[standalone Raspberry Pi installation guide]: /getting-started/installation-raspberry-pi/
[Voltage sensor]: /integrations/bloomsky/#sensor
[SNMP]: /integrations/snmp#sensor

3
source/_posts/2016-10-01-we-have-raspberry-image-now.markdown
View File

@ -12,7 +12,7 @@ Today we're happy to announce our brand new Raspberry Pi image! It is based on R
This image comes pre-installed with everything you need to get started with Home Assistant right away.
To get started, check out the installation instructions in [the getting started section][gs-image] or watch the latest video by [BRUHAutomation]:
To get started, check out the installation instructions in the getting started section or watch the latest video by [BRUHAutomation]:
<div class='videoWrapper'>
<iframe width="560" height="315" src="https://www.youtube.com/embed/iIz6XqDwHEk" frameborder="0" allowfullscreen></iframe>
@ -28,5 +28,4 @@ As it is today there is no pre-compiled Z-Wave support but it can be installed b
Happy Automating!
[gs-image]: /docs/installation/hassbian/installation/
[BRUHAutomation]: https://www.youtube.com/channel/UCLecVrux63S6aYiErxdiy4w

3
source/_posts/2017-02-03-hassbian-toybox.markdown
View File

@ -50,11 +50,10 @@ On the close horizon from [@Landrash][landrash-github] there a few more script i
To follow discussions about the development of the HASSbian image or to contribute join our [Discord chat server][discord].
To get started with the new image, check out the installation instructions in the [getting started section][gs-image].
To get started with the new image, check out the installation instructions in the getting started section.
[cec]: /integrations/hdmi_cec/
[hassbian-repo]: https://github.com/home-assistant/hassbian-scripts
[hassbian-avahi]: https://hassbian.local
[landrash-github]: https://github.com/Landrash
[gs-image]: /docs/installation/hassbian/installation/
[discord]: https://discord.gg/8X8DTH4

3
source/_posts/2017-04-30-hassbian-1.21-its-about-time.markdown
View File

@ -39,10 +39,9 @@ With this image there also quite a bit of cleaning of the base system and the sc
To follow discussions about the development of the HASSbian image or to contribute join our [Discord chat server][discord-devs].
To get started with the new image, check out the installation instructions in the [getting started section][gs-image].
To get started with the new image, check out the installation instructions in the getting started section.
[cec]: /integrations/hdmi_cec/
[hassbian-repo]: https://github.com/home-assistant/hassbian-scripts/
[hassbian-config-release]: https://github.com/home-assistant/hassbian-scripts/releases/latest
[gs-image]: /docs/installation/hassbian/installation/
[discord-devs]: https://discord.gg/8X8DTH4

2
source/_posts/2017-05-01-home-assistant-on-raspberry-pi-zero-in-30-minutes.markdown
View File

@ -71,5 +71,5 @@ Wait about 15-20 minutes and voilà you have your Home Assistant on your Raspber
To try it out, go to `http://hassbian:8123` or `http://hassbian.local:8123` if you're using Mac.
For further details about HASSbian, take a look at the [documentation](/docs/installation/hassbian/).
For further details about HASSbian, take a look at the documentation.

2
source/_posts/2017-05-13-home-assistant-on-orange-pi-zero.markdown
View File

@ -128,5 +128,3 @@ ha@orangepizero:~$ cd homeassistant && source bin/activate
<p class="img">
<img src="/images/blog/2017-05-orangepi/orange-pi-running.png" />
</p>
To make it ready for daily usage, don't forget to enable [autostart](/docs/autostart/).

3
source/_posts/2017-09-16-hassbian-1.3-a-bit-of-a-stretch.markdown
View File

@ -24,11 +24,10 @@ To allow you to customize your installation further, we have made a few addition
To follow discussions about the development of the HASSbian image or to contribute join our [Discord chat server][discord-hassbian].
To get started with the new image, check out the installation instructions on the [installing Hassbian page][install].
To get started with the new image, check out the installation instructions on the installing Hassbian page.
[landrash]: http://github.com/landrash
[ludeeus]: http://github.com/ludeeus
[hassbian-repo]: https://github.com/home-assistant/hassbian-scripts/
[hassbian-config-release]: https://github.com/home-assistant/hassbian-scripts/releases/latest
[install]: /docs/installation/hassbian/installation/
[discord-hassbian]: https://discord.gg/RkajcgS

4
source/_posts/2017-11-12-tor.markdown
View File

@ -25,7 +25,7 @@ The most amazing part? It is super easy to set up!
## Setting up Tor
Our [documentation](/docs/ecosystem/tor/) provides a detailed guide about setting up a [Tor's Hidden Service](https://www.torproject.org/docs/hidden-services.html.en). The setup is straight-forward:
The setup is straight-forward:
1. Install Tor. On a Debian-based system: `$ sudo apt-get install tor`. On Fedora: `$ sudo dnf install tor`
2. Modify Tor's main configuration file `/etc/tor/torrc` to include the following lines:
@ -97,4 +97,4 @@ The setup described in this blog post is easy and relatively secure, but anyone
This "Stealth"-mode adds an extra layer of security to your Hidden Service by only responding to a client that passes a unique secret cookie as it connects. Obviously, this requires additional configuration on the Tor client applications.
Additional information can be found in the [Tor documentation](/docs/ecosystem/tor/) and the [Tor add-on repository](https://github.com/hassio-addons/addon-tor), including how to setup the "Stealth"-mode. The Tor Project itself provides details about a variety of topics in their [documentation](https://www.torproject.org/docs/documentation.html.en).
The Tor Project itself provides details about a variety of topics in their [documentation](https://www.torproject.org/docs/documentation.html.en).

43
source/_redirects
View File

@ -2056,6 +2056,42 @@
/ecosystem/notebooks/stats https://data.home-assistant.io
/ios/whats-new https://companion.home-assistant.io/docs/getting_started/getting-started
# Migrated Community Guides
/cookbook/apache_configuration https://community.home-assistant.io/t/reverse-proxy-with-apache/196942
/cookbook/dropboxbackup https://community.home-assistant.io/t/backing-up-to-dropbox/196960
/cookbook/githubbackup https://community.home-assistant.io/t/sharing-your-configuration-on-github/195144
/cookbook/tls_domain_certificate https://community.home-assistant.io/t/certificate-for-ssl-tls-via-domain-ownership/196968
/cookbook/tls_self_signed_certificate https://community.home-assistant.io/t/certificate-authority-and-self-signed-certificate-for-ssl-tls/196970
/cookbook/tor_configuration https://community.home-assistant.io/t/tor-onion-service-configuration/195171
/docs/autostart/init.d https://community.home-assistant.io/t/autostart-using-init-d/199494
/docs/autostart/macos https://community.home-assistant.io/t/autostart-on-macos/199500
/docs/autostart/systemd https://community.home-assistant.io/t/autostart-using-systemd/199497
/docs/autostart/upstart https://community.home-assistant.io/t/autostart-using-upstart/199499
/docs/ecosystem/apache https://community.home-assistant.io/t/reverse-proxy-with-apache/196942
/docs/ecosystem/backup/backup_dropbox https://community.home-assistant.io/t/backing-up-to-dropbox/196960
/docs/ecosystem/backup/backup_github https://community.home-assistant.io/t/sharing-your-configuration-on-github/195144
/docs/ecosystem/backup/backup_usb https://community.home-assistant.io/t/backup-configuration-to-a-usb-drive/196964
/docs/ecosystem/caddy https://community.home-assistant.io/t/reverse-proxy-with-caddy/196943
/docs/ecosystem/certificates https://community.home-assistant.io/tags/c/community-guides/51/remote-access
/docs/ecosystem/certificates/lets_encrypt https://community.home-assistant.io/t/installing-tls-ssl-using-lets-encrypt/196975
/docs/ecosystem/certificates/tls_domain_certificate https://community.home-assistant.io/t/certificate-for-ssl-tls-via-domain-ownership/196968
/docs/ecosystem/certificates/tls_self_signed_certificate https://community.home-assistant.io/t/certificate-authority-and-self-signed-certificate-for-ssl-tls/196970
/docs/ecosystem/haproxy https://community.home-assistant.io/t/reverse-proxy-with-haproxy/196950
/docs/ecosystem/nginx https://community.home-assistant.io/t/reverse-proxy-using-nginx/196954
/docs/ecosystem/nginx_subdomain https://community.home-assistant.io/t/reverse-proxy-with-nginx-using-a-subdomain/196952
/docs/ecosystem/synology https://community.home-assistant.io/t/synology-dsm-reverse-proxy/199502
/docs/ecosystem/tor https://community.home-assistant.io/t/tor-onion-service-configuration/195171
/docs/installation/armbian https://community.home-assistant.io/t/home-assistant-core-python-on-armbian/196987
/docs/installation/centos https://community.home-assistant.io/t/installing-home-assistant-core-on-centos-rhel/199512
/docs/installation/fedora https://community.home-assistant.io/t/installing-home-assistant-core-on-fedora/199518
/docs/installation/freenas https://community.home-assistant.io/t/installation-of-home-assistant-on-your-freenas/195158
/ecosystem https://community.home-assistant.io/c/community-guides/51
/ecosystem/synology https://community.home-assistant.io/t/synology-dsm-reverse-proxy/199502
/getting-started/autostart https://community.home-assistant.io/t/autostart-using-upstart/199499
/getting-started/autostart-init.d https://community.home-assistant.io/t/autostart-using-init-d/199494
/getting-started/autostart-macos https://community.home-assistant.io/t/autostart-on-macos/199500
/getting-started/autostart-systemd https://community.home-assistant.io/t/autostart-using-systemd/199497
# Add-ons
/addons/cec_scan https://github.com/home-assistant/hassio-addons/blob/master/cec_scan/README.md
/addons/check_config https://github.com/home-assistant/hassio-addons/blob/master/check_config/README.md
@ -2082,3 +2118,10 @@
# Lovelace documentation
/lovelace/entity-button /lovelace/button
/lovelace/views /lovelace/dashboards-and-views
# Removed documentation
/docs/installation/hassbian /getting-started
/docs/installation/macos /docs/installation/virtualenv
/docs/installation/raspberry-pi-all-in-one /getting-started
/getting-started/hassbian /getting-started
/getting-started/installation-raspberry-pi-all-in-one /getting-started