vmware-marketplace

Bitnami How-To Guides for VMware Marketplace

Learn about the Bitnami HTTPS Configuration Tool

The Bitnami HTTPS Configuration Tool is a command line tool for configuring mainly HTTPS certificates on Bitnami stacks, but also common features such as automatic renewals, redirections (e.g. HTTP to HTTPS), etc. This tool is located in the installation directory of the stack at /opt/bitnami.

NOTE: This tool is only supported on 64-bit Linux operating systems. It cannot be used with IPv6 addresses or to configure HTTPS certificates for NGINX Web servers.

Run the Bitnami HTTPS Configuration Tool

The Bitnami HTTPS Configuration Tool is included in every Bitnami Stack released since May 10th 2019. In order to check whether your stack includes it or doesn’t, please check if it is present at /opt/bitnami/bncert-tool.

If your stack does not include the tool, you can download the latest version from this link.

NOTE: Before using the Bitnami HTTPS configuration tool, ensure that your domain’s DNS configuration correctly reflects the host’s IP address. You can update your domain’s DNS configuration through your DNS provider.

To run the Bitnami HTTPS Configuration Tool, follow the instructions below:

  • Log in to the server console. Refer to the FAQ for more information.

  • (Optional) Download the Bitnami HTTPS Configuration Tool:

      $ wget -O bncert-linux-x64.run https://downloads.bitnami.com/files/bncert/latest/bncert-linux-x64.run
  $ sudo mkdir /opt/bitnami/bncert
  $ sudo mv bncert-linux-x64.run /opt/bitnami/bncert/
  $ sudo chmod +x /opt/bitnami/bncert/bncert-linux-x64.run
  $ sudo ln -s /opt/bitnami/bncert/bncert-linux-x64.run /opt/bitnami/bncert-tool

  • Run the Bitnami HTTPS Configuration Tool:

      $ sudo /opt/bitnami/bncert-tool

  • The Bitnami HTTPS Configuration Tool tool first tries to find the Bitnami Stack. If it can’t find it you will be prompted to type its location. The default directory on Bitnami VMs and Cloud Images is /opt/bitnami on Bitnami VMs and Cloud Images.

  • After a valid installation has been found, the tool will automatically check for updates. If there is an available update it will ask you to download it. It is recommended to accept this option; your stack might not include the latest version.

  • Once the directory is found you will be prompted to enter the domains for which you want to create a certificate. You can pass multiple domains by separating them with spaces. The first domain will be used for determining if a certificate was already generated. Find below the different scenarios you can find:

  • If an existing certificate was not found, a new HTTPS certificate will be generated with Let’s Encrypt.

  • If an existing certificate already exists, but it is associated to different domains, you will be asked if it should be revoked and a new certificate be generated with Let’s Encrypt.

  • If an existing certificate already exists and it is associated to the same domains, the tool will proceed with renewing the certificate.

  • In the resulting screen, you can enable/disable useful redirections for your stack.

  • Next, accept the list of changes proposed for your installation. If you reject the changes (by selecting ‘No’), you will go back to the Domains page.

  • Then, you will be prompted for your e-mail address, and to agree to the Let’s Encrypt Terms of Service. The e-mail is used for certificate expiration notifications.

  • Finally, the tool will perform the changes and once finished, your website will have a valid HTTPS certificate.

NOTE: For application stacks, the Bitnami HTTPS Configuration Tool tool also uses the Bitnami Configuration Tool (bnconfig) tool to configure the domain name in the application and then renames the tool to bnconfig.disabled. This is done to avoid the configured domain name being reset on the next boot.

Troubleshooting

Manually revoking an existing certificate

Apache

If you are prompted to manually revoke a certificate, follow the steps below:

  • Enable dummy certificates in your web server configuration file by adding the following lines to the /opt/bitnami/apache/conf/bitnami/bitnami-ssl.conf and the /opt/bitnami/apache/conf/vhosts/APPNAME-https-vhost.conf files (where APPNAME depends on the application in use):

      SSLCertificateFile "/opt/bitnami/apache/conf/bitnami/certs/server.crt"
  SSLCertificateKeyFile "/opt/bitnami/apache/conf/bitnami/certs/server.key"

  • Restart your web server and ensure it does not fail:

      $ sudo /opt/bitnami/ctlscript.sh restart apache

  • Once the web server is configured to use dummy certificates, revoke the certificate with Lego. Remember to replace EMAIL and DOMAIN with the email address and main domain associated to the certificate, respectively:

      $ sudo /opt/bitnami/letsencrypt/lego --path /opt/bitnami/letsencrypt --tls --email=EMAIL --domains=DOMAIN revoke
NGINX

  • Enable dummy certificates in your web server configuration file by updating the ssl_certificate and ssl_certificate_key options in the /opt/bitnami/conf/nginx.conf, /opt/bitnami/conf/server_blocks/default-https-server-block.conf and /opt/bitnami/nginx/conf/server_blocks/APPNAME-https-server-block.conf files (where APPNAME depends on the application in use):

      ssl_certificate      /opt/bitnami/nginx/conf/bitnami/certs/server.crt;
  ssl_certificate_key  /opt/bitnami/nginx/conf/bitnami/certs/server.key;

  • Restart your web server and ensure it does not fail:

      $ sudo /opt/bitnami/ctlscript.sh restart nginx

  • Once the web server is configured to use dummy certificates, revoke the certificate with Lego. Remember to replace EMAIL and DOMAIN with the email address and main domain associated to the certificate, respectively:

      $ sudo /opt/bitnami/letsencrypt/lego --path /opt/bitnami/letsencrypt --tls --email=EMAIL --domains=DOMAIN revoke

Certificates not renewed automatically

In order to renew certificates in cron jobs, the Bitnami HTTPS Tool configures Let’s Encrypt to perform a HTTP challenge to verify the domains are still valid. This way it is not required to restart the web server and suffer downtime.

When running this tool, it performs the following actions:

  • Create a directory at /opt/bitnami/apps/letsencrypt/.well-known, and map it to http://SERVER-IP by configuring the web server. This directory will be used by Let’s Encrypt for storing a challenge file to verify the domains.
  • Check a sample file created inside .well-known can be fetched from http://SERVER-IP, to ensure the web server configuration is valid.

If the check fails (a sample file created inside .well-known is not accessible), it is highly probable that Let’s Encrypt will fail to perform the HTTP challenge and therefore the automatic certificate renewal will fail. Please check the following scenarios:

  • The web server configuration is invalid. Check that files inside /opt/bitnami/apps/letsencrypt/.well-known are accessible at http://SERVER-IP/.well-known for all domains.

  • Custom redirections are enabled. In such case you need to disable the redirection when accessing /.well-known by adding the following rule, right before the line performing the redirection, inside the virtual host:

      RewriteCond %{REQUEST_URI} !^/\.well-known

  • mod_proxy is used for handling requests to the application (without using a directive). In this case, to avoid /.well-known being affected by the proxy configuration, you need to add the line below before any “Location” directive.

      ProxyPass /.well-known !

  • mod_proxy is used for handling requests to the application within a directive. In this case, to avoid /.well-known being affected by the proxy configuration, you need to add the line below after any “Location” directive.

      <Location /.well-known>
      ProxyPass !
  </Location>

Adding domains

If you add one or more domains, run the Bitnami HTTPS Configuration Tool again and provide the complete list of domains to generate additional SSL certificates for the added domains.

Resetting the certificates

In case the certificate generation process fails and/or you wish to reset the certificates for any reson, follow the steps below:

  • Remove the cron jobs in the root and bitnami user’s cron table. Run the following commands and remove any lines/commands related to certificate renewal:

      $ sudo crontab -e
  $ sudo crontab -e -u bitnami

  • Modify the Web server configuration file to use the original (dummy) server.crt and server.key certificates.

  • Restart all Bitnami services:

      $ sudo /opt/bitnami/ctlscript.sh start

IMPORTANT: Users will see SSL certificate warnings when accessing the website while the dummy certificates are in use. These warnings will disappear after valid SSL certificates are installed for the website.

Check out the following tutorial if you want to learn more about configuring SSL with the Bncert tool:

Last modification December 21, 2022