View source for HTTPS Support via Let’s Encrypt

* Installed client: [https://github.com/Neilpang/acme.sh acme.sh] (the installation of the default client [https://certbot.eff.org/#ubuntuother-nginx certbot] failed due to some python incompatibilites)

== How Let's Encrypt works ==
"Let's Encrypt" is an initiative by the Mozilla Foundation and the Electronic Frontier Foundation that provides free SSL certificates for websites. The general idea is that if you control the content in the root directory of a domain, you are eligible to request the certificate for that domain. No paperwork or authentication required.

The certificate is issued automatically by running one of many supported clients on the target machine. It proves to the lets-encrypt server that the server is eligible, by placing a requested token at a requested path (that could look like <code>/.well-known/acme-challenge/iDdCv0Vs1ksYyuNRYfGaV79M0VmeQrzt6Ydgj8HP7EQ</code>).

The certificates are only valid for 90 days but can be automatically renewed via a cron job. Renewal is possible within 30 days of the certificate expiring. The cron job should run more often, as it will just ignore the renewal attempt if the certificate is too recent.

For the biowikifarm the certificate has to include the 50 different domains currently supported by the server. Therefore the certificate issuing and renewal take quite a while.

Further Information: 
* https://en.wikipedia.org/wiki/Let%27s_Encrypt
* https://letsencrypt.org/how-it-works/

== Updating the certificates for newly added wikis ==
* add new domains to <code>/root/generate_certificates.sh</code> and specify the root directory the domain points to
  sudo /root/.acme.sh/acme.sh --issue \
  -d biowikifarm.net -w /var/www \
  -d www.biowikifarm.net -w /var/www \
  -d abcd.biowikifarm.net -w /var/www/v-abcd \
  ...
: ''important side note: the first domain should always be <code>biowikifarm.net</code>, as the first domain will determine the name of the certificate which is already referenced in the nginx config. After <code>www.biowikifarm.net</code>, all other domains and subdomains are sorted alphabetically. Please add a new domain at the correct position.''
* run <code>sudo /root/generate_certificates.sh</code> (takes around 10 minutes)
* if you get a response like <code>Skip, Next renewal time is: ...</code>, add the option <code>--force</code> to the first line of <code>/root/generate_certificates.sh</code> and run it again
  sudo /root/.acme.sh/acme.sh --issue --force \
* the final keys and certificates are located at <code>/root/.acme.sh/biowikifarm.net/</code> and are already referenced in <code>/etc/nginx/nginx.conf</code>
* (not sure if necessary, but just to be sure) run <code>sudo service nginx reload</code>
* '''remove the option <code>--force</code> if you have added it to <code>/root/generate_certificates.sh</code>''', otherwise the cron job will generate a new certificate every time, instead of just checking if it needs to be renewed.

== Switching Wikis to HTTPS Only ==
It is relatively easy to adjust the nginx settings of the server, so that a particular domain only supports https and all http requests are forwarded accordingly. These changes must me made in the domain specific setting stored at <code>/etc/nginx/sites-available</code>. The settings so far should look something like this: 
<pre>
server {
	server_name example.biowikifarm.net;
	root /var/www/v-example;

	include /etc/nginx/biowikifarm_listen80_443.conf;
	include /etc/nginx/biowikifarm_generics.conf;
	include /etc/nginx/biowikifarm_generic_php.conf;
  
	location / { 
	...
</pre>

This section needs to be changed so that it looks like this: 
<pre>
server {
	# redirect requests via http to https
	listen 80; 
	server_name example.biowikifarm.net;
	return 301 https://$server_name$request_uri;
}

server {
	listen 443 ssl;
	server_name example.biowikifarm.net;
	root /var/www/v-example;

	include /etc/nginx/biowikifarm_generics.conf;
	include /etc/nginx/biowikifarm_generic_php.conf; 
  
	location / { 
	...
</pre>

Note that the line <code>include /etc/nginx/biowikifarm_listen80_443.conf;</code> was removed. This is important as it will result in a configuration error if it is still there.
After this, check if the configuration is valid and reload nginx. 
 sudo nginx -t
 sudo service nginx reload

The next step is to check the '''LocalSettings.php''' of the wiki, to see if the <code>$wgServer</code> variable is specified as http and adjust it accordingly. 
 $wgServer = "http://example.biowikifarm.net";
should be changed to 
 $wgServer = "https://example.biowikifarm.net";
If the variable is protocol independent
 $wgServer = "//example.biowikifarm.net";
or uses a request to determine the current protocol
 $wgProto = (isset($_SERVER['HTTPS']) && $_SERVER['HTTPS'] == 'on') ? 'https' : 'http';
 $wgServer = "$wgProto://example.biowikifarm.net";
it can be adjusted, but doesn't have to.

The next step is to check if any of the resources (most likely logo and thumbnail) are included using http links that will result in a mixed-content warning. Adjust those links to https as well. (see section [[#Mixed Content Warning|Mixed Content Warning]] for details).

After this all old http links will automatically be forwarded to https. It might happen that the cookies for logged in users are now invalid and they have to log in again.

== Trouble Shooting ==
When Let's Encrypt is run as a cronjob, the output of the job (both stdout and stderr) are recorded and stored at <code>/var/log/letsencrypt</code>. In case something fails with the certificate creation look in this directory for latest files to see what caused the creation to fail. 

=== Certificate Creation Fails ===
==== Root document for domain not properly configured ====
When generating a new certificate, either because a new domain was added or because the old certificate needs renewal, and a message like this appears
 Verify error:Could not connect to <nowiki>http://(sub.domain.tld)/.well-known/acme-challenge/iDdCv0Vs1ksYyuNRYfGaV79M0VmeQrzt6Ydgj8HP7EQ</nowiki>
check if you have specified the correct directory document root for the corresponding domain. 

==== Let's Encrypt certificates forbidden for the domain ====
 sub.domain.tld:Verify error:CAA record for sub.domain.tld prevents issuance
No Let's Encrypt certificate can be issued for the domain, because the CAA record for the domain is restricted to some specific certificate authorities and letsencrypt is not explicitly allowed. If you have the rights to do so, you can allow LE to issue certificates for the domain by adjusting the CAA record accordingly. If not then this domain needs to be removed from the LE config file and the certificate needs to be created by another mean. See also: https://letsencrypt.org/docs/caa/

If you have a dedicated certificate file for one specific domain, you can add it to the settings for this domain by opening the file <code>/etc/nginx/site-available/<domain-config-file></code> and adding the following lines to the corresponding server block
 server{
   listen 443 ssl;
   [...]
   ssl_certificate     /root/certificates/<domain>/fullchain.cer;
   ssl_certificate_key /root/certificates/<domain>/<domain>.key;
The files might be named differently, this just follows the LE convention.

=== Mixed Content Warning ===
[[File:Mixed content warning 1.png|thumb|300px|Mixed Content Warning for the Test Wiki. The warning is shown in a German version of Firefox.]]
When a wiki is accessed via https, it can happen that the browser shows a warning that the site is not secure. This is usually the case when some resources (e.g. images or style sheets), are loaded using insecure (i.e. http) connections. In Firefox this mean that the lock icon next to the URL in the address bar shows a yellow triangle. In Chrome a grey 'i' in a circle is shown. (Internet Explorer doesn't show this warning). 

To fix it, it is important to know which images are loaded using https. This can be easily done using Firefox's build in web console. 
# open the web console in Firefox using the keyboard shortcut <code>Ctrl+Shift+K</code>. 
# (re)load the desired page
# maybe deselect all of the other warnings and errors besides the one in the security category
# you can now see a list of all of the files that caused the Mixed Content Warning.  
#:[[File:Mixed content warning 2.png|thumb|900px|none|Taking a look at the web console of the browser to see which images cause the mixed content warning. The console is shown in a German version of Firefox.]]
#:* In this case, the logo and the thumbnail of the wiki as well as the creative commons graphic were loaded using http links.
# open the <code>LocalSettings.php</code> of the wiki and you should be able to find those links
#: <pre style="display:inline-block">
#:: ##Logo in upper left corner:
#:: $wgLogo="http://biowikifarm.net/testwiki/media/logo/test135.png";
#:: $wgFavicon="http://biowikifarm.net/testwiki/media/logo/favicon.png"; ## URL of the site favicon.
#:: ...
#:: $wgRightsIcon = "http://www.species-id.net/s/media/f/f3/CC-BY-SA_3_icon_88x31.png";
#::</pre>
# adjust the links to https (or alternatively protocolless like <code>//biowikifarm.net/testwiki/</code>)
# save the file
# reload the page in your browser
# And now the warning icon should be gone
#:[[File:Mixed content warning 3.png|thumb|300px|left|Mixed Content Warning is gone, instead the green lock icon appears in Firefox (similar green lock in Chrome).]]
[[Category:Trouble shooting]]