Troubleshoot SSL Issues
Bitnami stacks come with HTTPS enabled by default. To make this happen, we provide the following dummy SSL content:
- An auto-generated key-pair server.key
- A self-signed dummy certificate server.crt
- An autogenerated certificate authority server-ca.crt
While not suitable for production, these are more than enough for testing purposes. A user who wants to use a given application in production, must substitute these dummy certificates with valid SSL certificates (either purchased or generated using tools like Let's Encrypt). Just replace the three dummy files above and restart the Web server, as explained in this guide for Apache and this guide for Nginx.
Another typical practice is to force all traffic to be HTTPS-based (Bitnami applications allow both HTTP and HTTPS traffic). To do this, the user must add three directives in the server configuration, as explained in this guide for Apache and this guide for Nginx.
These processes, which are necessary for getting the application production ready, are where you'll usually encounter SSL issues.
In this how-to guide, you will learn how to deal with SSL errors in your application. You'll discover how Bitnami configures HTTPS by default, what the common issues are and how to fix issues in the stack.
How to detect
There are two levels of severity for these kinds of issues:
- Level 1: The site is operating with non-validated HTTPS
- Level 2: The server goes down
Level 1: Site operating with non-validated HTTPS
This level is very easy to detect, as the following message appears when you access the application via a browser.
Your connection is not private [...] ERR_CERT_AUTHORITY_INVALID
Level 2: The server goes down
This kind of error will normally be on the Apache side, giving an error message like this:
httpd could not be started
Going further into the logs, you'll most likely find errors regarding the .crt files, for instance:
server.crt: permission denied
Certificate and private key example.com:443:0 from server.crt and server.key do not match
The error messages can be quite different, but they all reference the certificate files.
These are the most common SSL issues that Bitnami users face:
Issue replacing the dummy certificates: This is where you have problems substituting the dummy certificate files we described at the top of this guide.
Changed default configuration: As HTTPS is enabled by default, you would only need to replace the dummy certificate files and restart the Web server, the rest is already dealt with. However, if users performed modifications in either the server configuration or the application configuration, this could cause unexpected issues.
HTTPS redirection: While forcing HTTPS redirection in the Web server settings, something fails. Typical problems might be an infinite redirection error, or the page not showing all the content properly.
Integration with Cloud Technologies: Users may want to integrate the application with cloud solutions that already provide SSL certificates, such as AWS Elastic Load Balancer (ELB), CloudFlare or Google Cloud Load Balancer. And sometimes, the integration can provoke issues.
Issues with Let's Encrypt: This tool allows the easy creation of a valid certificate for free. Mistakes with its execution can cause several errors.
Problems with the application configuration: Sometimes, it might be the case that substituting the certificate is not enough for the application to work with HTTPS. You may need to change certain settings such as the domain name (which can't be set straight out of the box).
Issues with the infrastructure: Some SSL verification operations fail because there is an issue with the server itself, such as a missing authority in curl, an incorrect firewall rule or wrong server datetime.
The following checklist covers the majority of the cases described above and will help you to find and debug most SSL issues.
Did you restart the Web server after installing the certificates?
The newly installed certificates will not be used until you restart Apache or Nginx:
$ sudo /opt/bitnami/ctlscript.sh restart apache $ sudo /opt/bitnami/ctlscript.sh restart nginx
Is the Let's Encrypt client crashing because of Python?
Let's Encrypt certbot is a Python client. With some stacks, there could be a conflict with the Python version included in them. If you see this error when executing certbot:
Cannot locate wrapped file
Then there is a conflict with the bundled Python version. Execute these commands before launching certbot again:
$ export PATH=$(echo $PATH | sed 's/.opt.bitnami.python.bin.//g') $ export CFLAGS=$(echo $CFLAGS | sed 's/.I.opt.bitnami.common.include//g')
Is the Let's Encrypt client failing to detect your Apache installation?
If the Let's Encrypt client fails because it cannot detect Apache, then execute certbot with these parameters:
./certbot-auto certonly --webroot -w /opt/bitnami/apps/APPNAME/htdocs/
Did you replace the SSL certificates correctly?
In some cases, the certificates aren't properly uploaded to the server, so Apache is still using the dummy ones. Perform the following checks:
- Check that the certificate files are located in:
- Certificate: /opt/bitnami/apache2/conf/server.crt
- Key: /opt/bitnami/apache2/conf/server.key
- CA: /opt/bitnami/apache2/conf/server-ca.crt
and as below for Nginx:
- Certificate: /opt/bitnami/nginx/conf/server.crt
- Key: /opt/bitnami/nginx/conf/server.key
- If the location is different, make sure you overwrite it using the cp command.
- Check that the certificate and key match each other using this guide.
- If they do not match, either try uploading the certificates again, or generate new ones.
Are you using any load balancer like ELB?
- Try accessing your instance without the load balancer enabled.
- If you are still getting issues, check that you installed SSL certificates properly.
- If these steps don't solve your problems, then you may have the wrong configuration in your load balancer. Contact your cloud provider for more support on the issue.
Did you change the default configuration?
Bitnami stacks come with HTTPS preconfigured. You only need to replace the default SSL certificates. After restarting the Web server, then SSL configuration should take effect. If you changed the configuration, we advise you to restore the original configuration (you can launch a new instance of the stack to see the default configuration) and just replace the certificate files.
Does your server have the correct date/time?
Some operations require the server to have the correct date and time, otherwise they fail. To check that, execute the following command in your machine:
If the date is incorrect, then install ntp using your system package manager. After a short time, the date will be properly synchronized.
Are you getting infinite redirection loops after forcing HTTPS traffic?
If you added Apache rules for forcing HTTPS redirection and you get this error:
Then the page is infinitely redirecting to itself. Check that:
- The redirection rules specified in this guide were added to /opt/bitnami/apache2/conf/bitnami/bitnami.conf.
- You did not miss any of the application extra steps to configure SSL.
The following resources may be of interest to you:
- How to enable HTTPS support with SSL certificates: Apache and Nginx
- How to force HTTPS redirection for all applications: Apache and Nginx
- Configure Elastic Load Balancing with SSL and AWS Certificate Manager for Bitnami applications on AWS
- Generate and Install a Let's Encrypt SSL Certificate for a Bitnami Application