<p>If you’re interested in logging in to Home Assistant while away, you’ll have to make your instance remotely accessible.</p>
<p>If you’re interested in logging in to Home Assistant while away, you’ll have to make your instance remotely accessible.</p>
<p>The most common approach is to set up port forwarding from your router to port 8123 on the computer that is hosting Home Assistant. General instructions on how to do this can be found by searching <codeclass="highlighter-rouge"><router model> port forwarding instructions</code>.</p>
<p>The most common approach is to set up port forwarding from your router to port 8123 on the computer that is hosting Home Assistant. General instructions on how to do this can be found by searching <codeclass="highlighter-rouge"><router model> port forwarding instructions</code>.</p>
<p>A problem with making a port accessible is that some Internet Service Providers only offer dynamic IPs. This can cause you to lose access to Home Assistant while away. You can solve this by using a free Dynamic DNS service like <ahref="https://www.duckdns.org/">DuckDNS</a>.</p>
<p>A problem with making a port accessible is that some Internet Service Providers only offer dynamic IPs. This can cause you to lose access to Home Assistant while away. You can solve this by using a free Dynamic DNS service like <ahref="https://www.duckdns.org/">DuckDNS</a>.</p>
<p>Remember: 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 <ahref="/blog/2015/12/13/setup-encryption-using-lets-encrypt/">set up encryption using Let’s Encrypt</a> blog post.</p>
<p>Remember: 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 <ahref="/blog/2015/12/13/setup-encryption-using-lets-encrypt/">set up encryption using Let’s Encrypt</a> blog post, or this <ahref="https://home-assistant.io/docs/ecosystem/certificates/lets_encrypt/">detailed guide</a> to using Let’s Encrypt with HA.</p>
<p>Protect your communication with a <ahref="/cookbook/tls_self_signed_certificate/">self-signed certificate</a> between your client and the Home Assistant instance.</p>
<p>Protect your communication with a <ahref="/cookbook/tls_self_signed_certificate/">self-signed certificate</a> between your client and the Home Assistant instance.</p>
<p>For another way to access your Home Assistant frontend, check out <ahref="/cookbook/tor_configuration/">the instructions how to use Tor</a>.</p>
<p>For another way to access your Home Assistant frontend, check out <ahref="/cookbook/tor_configuration/">the instructions how to use Tor</a>.</p>
Before exposing your Home Aassistant instance to the outside world it is ESSENTIAL that you have set a password following the advice on the <ahref="https://home-assistant.io/docs/configuration/basic/">http</a> page.
Before exposing your Home Assistant instance to the outside world it is ESSENTIAL that you have set a password following the advice on the <ahref="https://home-assistant.io/docs/configuration/basic/">http</a> page.
</p>
</p>
<p>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:</p>
<p>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:</p>
<ul>
<ul>
<li>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.</li>
<li>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.</li>
<li>You know the internal IP address of your router and can access your router’s configuration pages.</li>
<li>You know the internal IP address of your router and can access your router’s configuration pages.</li>
<li>You have already set up a password for your Home Assistant instance, following the advice on this page: <ahref="https://home-assistant.io/docs/configuration/basic/">http</a></li>
<li>You have already set up a password for your Home Assistant instance, following the advice on this page: <ahref="https://home-assistant.io/docs/configuration/basic/">http</a></li>
<li>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 an TLS/SSL certificate.</li>
<li>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.</li>
<li>You have a basic understanding of the phrases I have used so far.</li>
<li>You have a basic understanding of the phrases I have used so far.</li>
<li>You are not currently running anything on port 80 on your network (you’d know if you were).</li>
<li>You are not currently running anything on port 80 on your network (you’d know if you were).</li>
<li>If you are not using Home Assistant on a Debian/Raspian/Hassbian system you will be able to convert any of the terminology I use in to the correct syntax for your system.</li>
<li>If you are not using Home Assistant on a Debian/Raspian/Hassbian system you will be able to convert any of the terminology I use in to the correct syntax for your system.</li>
@ -100,7 +100,7 @@ Before exposing your Home Aassistant instance to the outside world it is ESSENTI
<p>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 .</p>
<p>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 .</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>We will be looking for a system to run like this (in this example I will pretend our exernal IP is 12.12.12.12):</p>
<p>We will be looking for a system to run like this (in this example I will pretend our external IP is 12.12.12.12):</p>
<divclass="language-text highlighter-rouge"><preclass="highlight"><code>Outside world -> 12.12.12.12:8123 -> your router -> 192.168.0.200:8123
<divclass="language-text highlighter-rouge"><preclass="highlight"><code>Outside world -> 12.12.12.12:8123 -> your router -> 192.168.0.200:8123
</code></pre>
</code></pre>
</div>
</div>
@ -112,7 +112,7 @@ Before exposing your Home Aassistant instance to the outside world it is ESSENTI
<p>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).</p>
<p>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).</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>To get around the issue of not being able to chain the IP addresses together (I can’t say I want to call 12:12:12: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 SSL certificate our incoming call will be requesting port 443 (because that is the SSL port, like the SSH port is always 22), but our port forwarding rule will forward this to our HA instance on port 8123. When this guide is completed we will run something like this:</p>
<p>To get around the issue of not being able to chain the IP addresses together (I can’t say I want to call 12:12:12: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 TSL/SSL certificate our incoming call will be requesting port 443 (because that is the SSL port, like the SSH port is always 22), but our port forwarding rule will forward this to our HA instance on port 8123. When this guide is completed we will run something like this:</p>
<divclass="language-text highlighter-rouge"><preclass="highlight"><code>Outside world -> https://examplehome.duckdns.org -> 12.12.12.12:443 -> your router -> 192.168.0.200:8123
<divclass="language-text highlighter-rouge"><preclass="highlight"><code>Outside world -> https://examplehome.duckdns.org -> 12.12.12.12:443 -> your router -> 192.168.0.200:8123
</code></pre>
</code></pre>
</div>
</div>
@ -125,7 +125,10 @@ Before exposing your Home Aassistant instance to the outside world it is ESSENTI
</code></pre>
</code></pre>
</div>
</div>
<p>You will receive an ouput similar to the image below:</p>
<p>You will receive an ouput similar to the image below:</p>
<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.</p>
<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.</p>
<p>Then type the following command to open the text file that controls your network connection:</p>
<p>Then type the following command to open the text file that controls your network connection:</p>
<p>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.</p>
<p>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.</p>
<h3><aclass="title-link"name="2---set-up-port-forwarding-without-ssl-and-test-connection" href="#2---set-up-port-forwarding-without-ssl-and-test-connection"></a> 2 - Set up port forwarding without SSL and test connection</h3>
<h3><aclass="title-link"name="2---set-up-port-forwarding-without-tlsssl-and-test-connection" href="#2---set-up-port-forwarding-without-tlsssl-and-test-connection"></a> 2 - Set up port forwarding without TLS/SSL and test connection</h3>
<p>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:</p>
<p>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:</p>
<p>Service name - Port Range - Local IP - Local Port - Protocol</p>
<p>Service name - Port Range - Local IP - Local Port - Protocol</p>
<p>You may also have other options (like ‘source IP’), these can usually be left blank or in their default state.</p>
<p>You may also have other options (like ‘source IP’), these can usually be left blank or in their default state.</p>
@ -178,11 +181,11 @@ Protocol - Both
</code></pre>
</code></pre>
</div>
</div>
<p>This will tell you your current external IP address</p>
<p>This will tell you your current external IP address</p>
<p>Type the external IP address in to the url bar with http:// in front and :8123 after like so (12.12.12.12 is my example!):</p>
<p>Type the external IP address in to the URL bar with http:// in front and :8123 after like so (12.12.12.12 is my example!):</p>
<p>Can you see your Home Assisstant 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.</p>
<p>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.</p>
<p>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 wifi 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.</p>
<p>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 wifi 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.</p>
<p>Can you see it now, from a device that is definitely not connected to your local network? Excellent! You now have a remotely accesible Home Assistant instance.</p>
<p>Can you see it now, from a device that is definitely not connected to your local network? Excellent! You now have a remotely accesible Home Assistant instance.</p>
<p>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.</p>
<p>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.</p>
@ -191,7 +194,7 @@ Protocol - Both
<p>Sign in and create an account using one of the id validation options in the top right corner.</p>
<p>Sign in and create an account using one of the id validation options in the top right corner.</p>
<p>In the domains section pick a name for your subdomain, this can be anything you like, and click add domain.</p>
<p>In the domains section pick a name for your subdomain, this can be anything you like, and click add domain.</p>
<p>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</p>
<p>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</p>
<p>On the top left of duckdns.org select the install option. Then pick your operating system from the list. In our example we will use a Raspberry Pi. In the dropdown box select the url you just created.</p>
<p>On the top left of duckdns.org select the install option. Then pick your operating system from the list. In our example we will use a Raspberry Pi. In the dropdown box select the URL you just created.</p>
<p>Duckdns.org will now generate personalised instructions for you to follow so that your device can update their website every time your IP address changes. Carefully follow the instructions given on duckdns.org to set up your device.</p>
<p>Duckdns.org will now generate personalised instructions for you to follow so that your device can update their website every time your IP address changes. Carefully follow the instructions given on duckdns.org to set up your device.</p>
<p>At the end of the instructions DuckDNS will suggest you set up port forwarding. No need, we have already done this in step 2.</p>
<p>At the end of the instructions DuckDNS will suggest you set up port forwarding. No need, we have already done this in step 2.</p>
<p>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 your device running Home Assistant will update DuckDNS every time it changes.</p>
<p>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 your device running Home Assistant will update DuckDNS every time it changes.</p>
@ -201,14 +204,14 @@ Protocol - Both
</div>
</div>
<p>What now happens behind the scenes is this:</p>
<p>What now happens behind the scenes is this:</p>
<ul>
<ul>
<li>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 Assisstant)</li>
<li>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)</li>
<li>Your router receives the request on port 8123 and checks the port forwarding rules</li>
<li>Your router receives the request on port 8123 and checks the port forwarding rules</li>
<li>It finds the rule you created in step 2 and forwards the request to your HA instance</li>
<li>It finds the rule you created in step 2 and forwards the request to your HA instance</li>
<li>Your browser displays your Home Assisstant instance frontend.</li>
<li>Your browser displays your Home Assistant instance frontend.</li>
</ul>
</ul>
<p>Did it work? Super!</p>
<p>Did it work? Super!</p>
<p>You now have a remotely accesible 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 SSL, read on to find out how.</p>
<p>You now have a remotely accesible 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.</p>
<h3><aclass="title-link"name="4---obtain-an-tlsssl-certificate-from-lets-encrypt" href="#4---obtain-an-tlsssl-certificate-from-lets-encrypt"></a> 4 - Obtain an TLS/SSL certificate from Let’s Encrypt</h3>
<h3><aclass="title-link"name="4---obtain-a-tlsssl-certificate-from-lets-encrypt" href="#4---obtain-a-tlsssl-certificate-from-lets-encrypt"></a> 4 - Obtain a TLS/SSL certificate from Let’s Encrypt</h3>
<p>First we need to set up another port forward like we did in step 2. Set your new rule to:</p>
<p>First we need to set up another port forward like we did in step 2. Set your new rule to:</p>
<divclass="language-text highlighter-rouge"><preclass="highlight"><code>Service name - ha_letsencrypt
<divclass="language-text highlighter-rouge"><preclass="highlight"><code>Service name - ha_letsencrypt
Port Range - 80
Port Range - 80
@ -224,7 +227,7 @@ In cases where your ISP blocks port 80 you will need to change the port forward
<p>Now SSH in to the device your Home Assistant is running on.</p>
<p>Now SSH in to the device your Home Assistant is running on.</p>
<pclass="note">
<pclass="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 <codeclass="highlighter-rouge">sudoers</code> 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 <codeclass="highlighter-rouge">sudoers</code> list before continuing. If you are running the ‘standard’ pi setup, from your ‘pi’ user issue the following command (where <codeclass="highlighter-rouge">hass</code> is the Home Assistant user):
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 <codeclass="highlighter-rouge">sudoers</code> 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 <codeclass="highlighter-rouge">sudoers</code> list before continuing. If you are running the ‘standard’ pi setup, from your ‘pi’ user issue the following command (where <codeclass="highlighter-rouge">hass</code> is the Home Assistant user):
<p>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:</p>
<p>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:</p>
<h3><aclass="title-link"name="5---check-the-incoming-conection"href="#5---check-the-incoming-conection"></a> 5 - Check the incoming conection</h3>
<h3><aclass="title-link"name="5---check-the-incoming-conection"href="#5---check-the-incoming-conection"></a> 5 - Check the incoming conection</h3>
<pclass="note">
<pclass="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 your <codeclass="highlighter-rouge">homeassistant</code> folder:
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 your <codeclass="highlighter-rouge">homeassistant</code> folder:
<codeclass="highlighter-rouge">bash
<codeclass="highlighter-rouge">
$ cd ~/.homeassistant
$ cd ~/.homeassistant
</code>
</code>
If you use samba shares to edit your files you can exit your SSH now.
If you use samba shares to edit your files you can exit your SSH now.
<p>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.</p>
<p>Note the <strong>S</strong> 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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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 <strong>S</strong> after http):</p>
<p>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 <strong>S</strong> after http):</p>
@ -299,7 +302,7 @@ Protocol - Both
</code></pre>
</code></pre>
</div>
</div>
<p>…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.</p>
<p>…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.</p>
<p>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 ignore the warnings.</p>
<p>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.</p>
<p>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. Instructions for creating your new webapp can be found here:</p>
<p>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. Instructions for creating your new webapp can be found here:</p>
Travis CI