Added SSL guide to cookbook by point-4ward · Pull Request #2269 · home-assistant/home-assistant.io

point-4ward · 2017-03-16T10:32:33Z

Added SSL guide to cookbook. Contains an image, which I have put in the images folder.

Hope this is ok?

2 files - SSL guide and a screenshot The SSL guide is a comprehensive guide for the novice to get an external connection with SSL certificate and auto-renews where possible, with various notes for other eventualities.

bdurrer

Thanks for making the effort to write this guide. Please don't be offended by my comments. These are just suggestions of a interested reader and fellow coder 😄

bdurrer · 2017-03-17T12:01:09Z

+http://12.12.12.12:8123
+```
+
+Can you see your HA instance?  Awesome! 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.


The fact that you put loopback in quotes suggests that it has a meaning which a lot of users don't understand.
I guess it should either be explained or left out.

Fair point, I was kinda hoping in the context that it would just 'make sense', any suggestions for an explanatory sentence?

errm no, I don't have a better explanation. I guess that problem won't happen often anyway.

bdurrer · 2017-03-17T12:01:53Z

+
+Can you see your HA instance?  Awesome! 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 actualy 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.


It's actually, two L 😄
Maybe transform to a checklist instead of one big sentence

Ha, I didn't use spell check for the entire guide, so if you only found one spelling mistake I'm well happy!

I'll correct when I get a sec.

Spelling corrected.

bdurrer · 2017-03-17T12:09:16Z

+
+ * You can access your HA 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 set up a password for your HA instance, following the advice on this page: [http](https://home-assistant.io/docs/configuration/basic/)


The fact that a password should be set up BEFORE opening the router's firewall cannot be stressed enough.
I think there should be a fat warning note on the beginning of the page.

I agree, I'll add a warning when I get a sec.

Warning added.

bdurrer · 2017-03-17T12:18:07Z

+Remember to save the new rule.
+
+<p 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 HA 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!


I know what we are talking about here, but I still had a hard time reading that note (but then, I don't have an suggestion to change it besides writing shorter sentences in general 😏 ) .

Also I do wonder how a "noob" could detect or know that port 80 is blocked? But I guess when it gets longer it would require an extra troubleshooting section

Yeah, this is kinda what I meant in the opening section about not covering every eventuality, and why I said 'novice' rather than noob. If you can think of a better way to word this bit I'm all ears :-)

bdurrer · 2017-03-17T12:21:48Z

+
+
+<p 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 HA user.  There are commands below that require the HA 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 HA user on the sudoers list before continuing.  If you are running the 'standard' pi setup, from your 'pi' user issue the following command (where <hass> is the HA user):


Technical Question: Why does the user need to be on the sudoers list? I think it's not a good idea to give homeassistant that priviledge, since it's running the web services.
EDIT: Ah certbot needs root in --standalone mode. Bummer.

I guess that could be avoided by adding an extra user and create wrapper scripts which do su to that extra user... well yeah, thats probably too complicated, the guide is already very extensive 👍

Yeah, there are ways around this, but as a catch-all for a guide it seems like the easiest and isn't that insecure in the grand scheme of things.

bdurrer · 2017-03-17T12:31:59Z

+Protocol - Both
+```
+
+If during step 4 you had to use port 443 instead of port 80 to generate your certificate, you should delete that rule now.


Maybe rewrite or reorder to line 301 to make clear which rule you mean with "delete that rule"

Noted, I'll reorder when I get a sec.

bdurrer · 2017-03-17T12:35:29Z

+  base_url: examplehome.duckdns.org
+```
+
+You may wish to set up other options for the http component at this point, these extra options are beyond the scope of this guide but can be found on the http component page here: [http](https://home-assistant.io/components/http/)


Style hint: More full stops would improve the text 😉

bdurrer · 2017-03-17T12:37:42Z

+
+...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 ignore the warnings.


That's way too technical, without explaining the technical terms. I suggest to just remove it.

It's again about the loopback. Which I don't know how to explain in two or less sentences 😄

bdurrer · 2017-03-17T12:38:51Z

+ha_ssl and ha_letsencrypt
+```
+
+If you have any more for HA 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.


"any more" of what?

Rules, is it really that unclear? I think when it is 'presented' and formatted it will look right, but if it doesn't I'll reword it. Not sure what to though?

Yeah it might be the formatting. Speaking of, I suggest you put the rule names as code.
PS: Line 366 has a typo: "You chould now"

Typo corrected - will have to see how clear it is when it is rendered and if there are any issues with clarity I will fix with a further PR.

bdurrer · 2017-03-17T12:41:11Z

+
+Please remember whether you are a ONE-RULE person or a BOTH-RULE person for step 8!
+
+LetsEncrypt certificates only last for 90 days.  When they have less than 30 days left they can be renewed.  Renewal is a simple process.


That might be helpful further up to explain what the guide wants to tell us with "renewal"

Sorry, I don't get this one, can you clarify please?

Thanks for all the feedback so far :-D

On 229 the talk is about automatic renewal, but I guess some readers wonder why that is necessary.
But I don't know where a better place is than down here :)

Additions and corrections.

point-4ward · 2017-03-30T16:22:50Z

Added a few bits and corrected a few bits, should be good to go...

fabaff

I will merge it, move it to the Docs section, and fix the remaining issues.

New examples/documentation can go to current if there is no dependency to the main repo.

Marc Forth added 2 commits March 16, 2017 10:29

Screenshot for SSL_guide

a0b48d6

SSL Guide

7c028c3

2 files - SSL guide and a screenshot The SSL guide is a comprehensive guide for the novice to get an external connection with SSL certificate and auto-renews where possible, with various notes for other eventualities.

bdurrer reviewed Mar 17, 2017

View reviewed changes

Landrash added the Ecosystem label Mar 19, 2017

Update SSL guide.md

9537236

Additions and corrections.

bdurrer approved these changes Mar 30, 2017

View reviewed changes

fabaff approved these changes Mar 31, 2017

View reviewed changes

fabaff merged commit 8da09ab into home-assistant:next Mar 31, 2017


		Can you see your HA instance? Awesome! 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 actualy 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 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 HA user. There are commands below that require the HA 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 HA user on the sudoers list before continuing. If you are running the 'standard' pi setup, from your 'pi' user issue the following command (where <hass> is the HA user):


		...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 ignore the warnings.


		Please remember whether you are a ONE-RULE person or a BOTH-RULE person for step 8!

		LetsEncrypt certificates only last for 90 days. When they have less than 30 days left they can be renewed. Renewal is a simple process.

Uh oh!

Conversation

point-4ward commented Mar 16, 2017

Uh oh!

bdurrer left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

point-4ward commented Mar 30, 2017

Uh oh!

fabaff left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants