vmware-marketplace

Bitnami How-To Guides for VMware Marketplace

Troubleshoot SSL Issues

Introduction

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 these instructions for Apache and these instructions for NGINX.

IMPORTANT: For security reasons, never post or disclose your server’s SSL private key in a public forum.

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 section 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

Or:

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.

Common issues

These are the most common SSL issues that Bitnami users face:

  • 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.

  • Let’s Encrypt: This tool allows the easy creation of a valid certificate for free. Mistakes with its execution can cause several errors.

  • 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).

  • 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.

Troubleshooting checklist

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 the server is still using the dummy ones. Perform the following checks:

  • Check that the certificate files are located as below for Apache:

    • Certificate: /opt/bitnami/apache/conf/server.crt
    • Key: /opt/bitnami/apache/conf/server.key
    • CA: /opt/bitnami/apache/conf/server-ca.crt

    and as below for NGINX:

    • Certificate: /opt/bitnami/nginx/conf/bitnami/certs/server.crt
    • Key: /opt/bitnami/nginx/conf/bitnami/certs/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?

Some solutions like AWS Elastic Load Balancer (ELB) or CloudFlare provide SSL certificates as well. If you are having issues with SSL validity:

  • 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:

$ date

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:

ERR_TOO_MANY_REDIRECTS

Then the page is infinitely redirecting to itself. Check that:

  • The redirection rules specified in this guide were added to /opt/bitnami/apache/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:

The following video shows how to Check your SSL configuration:

Last modification August 25, 2023