oracle

Bitnami How-To Guides for Oracle Cloud Infrastructure Classic

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.

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.

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.

Troubleshooting

Manually revoking an existing certificate

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

  • Enable dummy certificates in your web server. Open the /opt/bitnami/apache2/conf/bitnami/bitnami.conf file and update the following lines:

    SSLCertificateFile "/opt/bitnami/apache2/conf/server.crt"
    SSLCertificateKeyFile "/opt/bitnami/apache2/conf/server.key"
    
  • Restart your web server and ensure it does not fail:

    $ sudo /opt/bitnami/ctlscript.sh stop 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
    

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 virtual hosts are enabled. For the Let’s Encrypt HTTP challenge to work with custom virtual hosts, the following configuration must be added to the respective VirtualHost directives in the httpd-vhosts.conf file:

    Alias /.well-known/ "/opt/bitnami/apps/letsencrypt/.well-known/"
    <Directory "/opt/bitnami/apps/letsencrypt/.well-known">
        Options +MultiViews
        AllowOverride None
        Require all granted
    </Directory>
    
  • 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:

    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>
    

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

Last modification October 30, 2019