How To Configure Zenoss 4.2.x To Use SSL

Prerequisites

• Optional: A signed SSL certificate from a trusted certificate authority (CA)

Applies To

• Zenoss 4.2.5
• Zenoss 4.2.4
• Zenoss 4.2.3
• Zenoss 4.2.2

Summary

The Nginx load balancer installed with Zenoss can be configured to encrypt connections to and from user browser sessions using the Hypertext Transfer Protocol Secure (HTTPS), that consists of the Hypertext Transfer Protocol (HTTP) running on top of the Secure Sockets Layer (SSL).

The following procedures describe how to to enable HTTPS connections to your Zenoss instance and how to repair broken graph displays.

Note: The instructions below result in a self-signed certificate; modify them as necessary to use an SSL certificate signed by a certificate authority.

Note: Certain web browser security updates disable JavaScript calls to insecure (HTTP) content from within secure (HTTPS) pages. As a result, in some cases where you have remote collectors and use HTTPS (or an out-of-band SSL-enabled load balancer), the panning and zooming function for graphs of devices on remote collectors stops working. If you encounter this situation, follow the procedure in the section below titled How to Proxy ZenRender Traffic.

Procedures

Configure Zenoss for HTTPS

1. Switch to the zenoss user (from root):
   # su - zenoss
   Run the following commands as the zenoss user.
2. Create a directory in which to store certificate and key files:
   $ mkdir /opt/zenoss/etc/ssl
3. Change into the new directory:
   $ cd /opt/zenoss/etc/ssl
4. Create the server private key:
   $ openssl genrsa -des3 -out zenoss.key 1024
5. Create the signing request:
   $ openssl req -new -key zenoss.key -out zenoss.csr
6. Remove the pass phrase requirement:
   $ cp zenoss.key zenoss.key.orig
   $ openssl rsa -in zenoss.key.orig -out zenoss.key
7. Sign the certificate:
   $ openssl x509 -req -days 365 -in zenoss.csr -signkey zenoss.key -out zenoss.crt
8. Stop the Zenoss web server daemons:
   $ zenwebserver stop
9. Change the ownership and permissions of the Ngnix executable so that it runs as the root user. Because /opt/zenoss/bin/ngnix is usually a symbolic link, the readlink command is used to get its actual location. Enter the password for the root user when prompted:
   $ su -c 'target="`readlink /opt/zenoss/bin/nginx`" && chown root:zenoss "$target" && chmod 04750 "$target"'
10. Verify that the ownership and permissions of the Nginx executable are correct:
    $ ls -lL /opt/zenoss/bin/nginx

    The first part of the output should read -rwsr-x--- 1 root zenoss.

11. Edit /opt/zenoss/etc/zenwebserver.conf to enable SSL and to refer to the SSL key and certificate files:
    1. Change useSSL False to useSSL True.
    2. Uncomment (remove the leading pound sign and space (“# ”) from) the sslport line, and optionally specify a different SSL port on which Ngnix should accept connections.

       Note that the default value, 443, is the standard port for HTTPS connections.

    3. Uncomment the sslCert line; and, if necessary, update the full path to the SSL certificate file.
    4. Uncomment the sslKey line; and, if necessary, update the full path to the SSL key file.
12. Start the Zenoss web server daemons:
    $ zenwebserver start
13. Reconfigure the load balancer:
    $ zenwebserver configure
14. Reload the load balancer:
    $ zenwebserver reload

Note: Depending on their browser security settings, users connecting to your Zenoss instance might encounter warning messages stating that the site's identity cannot be verified. These errors are generated by some browsers when a web server presents a self-signed certificate. These warnings can be eliminated by obtaining a signed certificate from a trusted CA.

How to Proxy ZenRender Traffic

Note: Remote collectors created by Resource Manager version 4.2.4 or greater will already have the corresponding nginx configuration files with the correct set of directives.

Note: If you have custom Nginx rules, ensure the primary server block in $ZENHOME/etc/nginx.conf contains the following directive:
include /opt/zenoss/etc/nginx-dc-*.conf;

1. Set Collector URL Configuration

   Perform the following steps for each remote collector:

   1. Navigate to Advanced > Collectors > [remote-collector-name] > Edit.
   2. Make note of the value in "Render URL", in case you need to rollback the changes made while executing this procedure.
   3. Make note of the value in "hostname" for use in step 2 below.
   4. Set the value of Render URL to:
      /remote-collector/[remote-collector-name]
   5. Click Save.
2. Configure / Verify Proxy Rules

   Use the following steps to configure proxying for ZenRender. If you want to configure proxying for ZenHub, contact Zenoss Support.

   1. Switch to the zenoss user if necessary:
      # su - zenoss
   2. Change to the Zenoss configuration directory:
      $ cd $ZENHOME/etc
   3. List the Nginx remote collector configuration files:
      $ ls nginx-dc-collector-*.conf
   4. List the current set of collectors:
      $ dc-admin list
   5. For each collector other than localhost, if the corresponding nginx-dc-collector file does not exist, create it and copy in the directives listed below.
      
      If the configuration file does exist and does not contain the directives listed below, create a backup of the file and then update it to include those lines.
      
      In either case, replace both occurrences of the string [remote-collector-name] with the actual name of the collector as displayed by the dc-admin list command.

   location ^~ /remote-collector/[remote-collector-name]/ {
       rewrite ^/remote-collector/[remote-collector-name]/(.*)$ /$1 break;
       proxy_pass http://[remote collector hostname]:8091;
   
       proxy_read_timeout 600s;
       client_max_body_size 500m;
       proxy_set_header        Host    $host;
       proxy_set_header        X-Real-IP $remote_addr;
       proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
       }
   

3. Reload the Nginix Configuration

   Perform the following steps to reload the configuration:

   1. Restart the web server if you made changes to the proxy rules in step 2 above:
      # zenwebserver restart
   2. Verify that graph zooming and panning are working for a device assigned to a remote collector. If zooming or panning does not work correctly, reset the Render URL field to its original value as in step 1 above, and contact Zenoss Support.