As part of the post-installation process, you might want to set up your Secure Sockets Layer (SSL) certificates. Setting up SSL certificates is optional when installing SaltStack Config, but recommended.

Before you start

Setting up the SSL certificates is one post-installation step in a series of several steps that should be followed in a specific order. First, complete one of the installation scenarios and then read the following post-installation pages:

Set up and configure SSL certificates

To create the SSL certificates:

  1. The python36-pyOpenSSL package is necessary to configure SSL after installation. This step is usually completed before installation. If you were unable to install it before installation, it can be installed now. For instructions about checking for and installing this dependency, see Install or upgrade Salt.
  2. Create and set permissions for the certificate folder for the RaaS service.
    sudo mkdir -p /etc/raas/pki
sudo chown raas:raas /etc/raas/pki
sudo chmod 750 /etc/raas/pki
  3. Generate keys for the RaaS service using Salt, or provide your own.
    sudo salt-call --local tls.create_self_signed_cert tls_dir=raas
sudo chown raas:raas /etc/pki/raas/certs/localhost.crt
sudo chown raas:raas /etc/pki/raas/certs/localhost.key
sudo chmod 400 /etc/pki/raas/certs/localhost.crt
sudo chmod 400 /etc/pki/raas/certs/localhost.key
  4. To enable SSL connections to SaltStack Config user interface, generate a PEM-encoded SSL certificate or ensure that you have access to an existing PEM-encoded certificate.
  5. Save the .crt and .key files you generated in the previous step to /etc/pki/raas/certs on the RaaS node.
  6. Update the RaaS service configuration by opening /etc/raas/raas in a text editor. Configure the following values, replacing <filename> with your SSL certificate filename:
    tls_crt:/etc/pki/raas/certs/<filename>.crt
tls_key:/etc/pki/raas/certs/<filename>.key
port:443
  7. Restart the RaaS service.
    sudo systemctl restart raas
  8. Verify the RaaS service is running.
    sudo systemctl status raas
  9. Confirm that you can connect to the user interface in a web browser by navigating to your organization’s custom SaltStack Config URL and entering your credentials. For more information about logging in, see Log in for the first time and change default credentials.

Your SSL certificates for SaltStack Config are now set up.

Updating SSL certificates

Instructions for updating SSL certificates for SaltStack Config are available at the VMware knowledge base. For more information, see How to update SSL certificates for SaltStack Config.

Troubleshooting SaltStack Config environments with vRealize Automation that use self-signed certificates

This workaround is for customers who are working with vRealize Automation deployments that use a certificate signed by a non-standard certificate authority.

SaltStack Config might experience the following symptoms:

  • When you first open vRealize Automation, your web browser displays a security warning next to the URL or in the display page that the certificate cannot be validated.
  • When you attempt to open the SaltStack Config user interface in your web browser, you might get a 403 error or a blank screen.

These symptoms might be caused if your vRealize Automation deployment is using a certificate signed by a non-standard certificate authority. To verify whether this is causing SaltStack Config to display a blank screen, SSH into the node that is hosting SaltStack Config and review the RaaS log file (/var/log/raas/raas). If you find a traceback error message that indicates that self-signed certificates are not allowed, the following workaround can possibly solve this issue.

Note:

As a security best practice, you should never set up a production environment to use self-signed certificates or improperly signed certificates to authenticate vRealize Automation or SaltStack Config. The recommended practice is to use certificates from trusted certificate authorities instead.

If you choose to use self-signed or improperly signed certificates, you may put your system at serious risk of a security breach. Proceed with caution when using this procedure.

If you experience this problem and your environment needs to continue using a certificate signed by a non-standard certificate authority, the solution is to add the vRealize Automation certificate CA to your SaltStack Config environment, as explained in the following workaround.

This workaround requires:

  • Root access
  • The ability to SSH into the RaaS server
Note:

As an additional security best practices, only the most trusted and senior individuals at your organization should be granted this level of access. Take care to restrict root access to your environment.

You may find it easier to create a private certificate authority and sign your own vRealize Automation certificates with that certificate authority rather than using self-signed certificates. The advantage of this approach is you only have to go through this process once for every vRealize Automation certificate you need. Otherwise, you would have to go through this process for every vRealize Automation certificate you create. For more information about creating a private certificate authority, see How do you sign a certificate request with your own certification authority (Stack Overflow).

To add a certificate signed by a non-standard certificate authority to the list of certificate authorities in SaltStack Config:

  1. Attempt to open the vRealize Automation web interface in your browser. The certificate should display a warning message in the browser window and the URL display.
  2. Download the required certificate.
    • For Chrome browsers: Click the Not Secure warning in the URL display to open a menu. Select Certificate (invalid). Drag the missing certificate to your local computer's file explorer or finder to save it. Choose the certificate signer (CA) if it is available. Click the certificate icon and then drag it to your local computer's file explorer. If the file extension is not .pem (.crt .cer .der), use the following command to convert it to .pem format: openssl x509 -inform der -in certificate.cer -out certificate.pem
    • For Firefox browsers: Click the warning icon in the URL display to open a menu. Select Connection not secure > More information. In the dialog box, click View certificate. Click the missing certificate to download it to your local computer's file system.
  3. If you haven’t already, SSH into the RaaS server.
  4. Append the certificate file to the end of the file in this directory: /etc/pki/tls/certs/ca-bundle.crt. You can append the certificate to the end of file using the following command, replacing the example file with your actual filename:
    cat <certificate-file>.crt  >> /etc/pki/tls/certs/ca-bundle.crt
    Note:

    You can also copy files with the .pem extension using this command.

  5. Navigate to the directory /usr/lib/systemd/system and open the file raas.service in your editor. Add the following line to this file anywhere above the ExecStart line:
    Environment=REQUESTS_CA_BUNDLE=/etc/pki/tls/certs/ca-bundle.crt
  6. Reload the daemon and restart RaaS using these commands: 
    systemctl daemon-reload
systemctl stop raas
rm /var/log/raas/raas
systemctl start raas
tail -f /var/log/raas/raas
    Note:

    Use tail -f /var/log/raas/raas to show the RaaS log file in continuous display, which may help with troubleshooting.

  7. Verify that this solution has solved the problem by logging into the SaltStack Config web interface. If the problem has been resolved, SaltStack Config displays the Dashboard page.

What to do next

After setting up SSL certificates, you may need to complete additional post-installation steps.

If you are a SaltStack SecOps customer, the next step is to set up these services. For more information, see Configure SaltStack SecOps.

If you've completed all the necessary post-installation steps, the next step is to integrate SaltStack Config with vRealize Automation SaltStack SecOps. See Create a SaltStack Config integration with vRealize Automation for more information.