Configuring NGINX for SSL Termination

NGINX is a reverse proxy and load balancer for http servers. It is commonly used for SSL Termination, offloading CPU-intensive operations. This document provides a base configuration that can help the edgeSuite administrator get NGINX configured in front of an edgeSuite instance.

Installation of NGINX #

Please follow NGINX’s official documentation for installing: https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/. It provides options for installing NGINX OpenSource or NGINX Plus.

The following is a good tutorial of NGINX and its features / configuration: https://www.digitalocean.com/community/tutorials/how-to-set-up-nginx-load-balancing-with-ssl-termination

Sample NGINX Configuration #

The following sample nginx.conf is used as a point of reference. Once downloaded, you can place it in one of the following directories: /usr/local/nginx/conf/etc/nginx , or /usr/local/etc/nginx. On the test system, it was placed in /usr/local/etc/nginx/nginx.conf.

The following sections will outline uses upstream to declare a single node edgeSuite endpoint. If you decide to load balance multiple edgeSuite servers, you would need to add the sticky session or route directive that will require NGINX Plus.

edgeSuite Configuration (added in version 3.9.2+) #

edgeSuite by default does not process ‘X-Forwarded-‘ header information to generate links / redirects. When using a proxy or load-balancer that injects the X-Forwarded headers, edgeSuite needs to have that feature enabled. To enable this feature, you will apply either the UNIX or Windows configuration below. Otherwise it is possible to configure ‘proxy_redirect’ rules to ensure host, port, and scheme changes are properly replaced by the proxy server.

On UNIX, edit the conf/environment.sh file and make sure the following line is set:

USE_FORWARD_HEADERS=true

On Windows, edit the conf/environment.bat file and make sure the following line is set:

set USE_FORWARD_HEADERS=true

Base Worker, Log, and Connection Settings

At the top of the sample file, you will see some general settings used to configure the resources NGINX will use to service requests:

worker_processes 5; ## Default: 1
error_log logs/error.log error;
pid logs/nginx.pid;
worker_rlimit_nofile 8192;
events {
worker_connections 4096; ## Default: 1024
}

Upstream Backends (optional) #

The following upstream edgeSuite setting provides a way to list one or more backends that will be proxied by NGINX.  Although this is listed, it is not used in the sample nginx.conf configuration.

upstream edgesuite {
      server 10.0.0.2:8080;
}

Server SSL   #

        listen                        8443 ssl; # ‘ssl’ parameter tells NGINX to decrypt the traffic

ssl                             on

        server_name            <hostname>;

        ssl_certificate            /usr/local/etc/nginx/ssl/hostname.crt;

        ssl_certificate_key    /usr/local/etc/nginx/ssl/hostname.key;

        #ssl_certificate          hostname.crt; # The certificate file

        #ssl_certificate_key  hostname.key; # The private key file

Header Configuration #

To configure content handling and security headers, use the following block:

        add_header X-Frame-Options SAMEORIGIN;

        add_header X-XSS-Protection “1; mode=block”;

        add_header X-Content-Type-Options nosniff;

        add_header Referrer-Policy origin-when-cross-origin;

Proxy Headers #

This section will describe what edgeSuite server is being proxied; optionally you can use http://edgeSuite when using the upstream configuration.

            #Use if upstream backends is not used.

            proxy_pass http://hostname:port;

            # Alternative config when using the upstream configuration.

            #proxy_pass http://edgesuite;

            proxy_set_header Host $host:$server_port;

            #proxy_set_header Accept-Encoding “”;

            proxy_set_header X-Real-IP $remote_addr;

            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

            proxy_set_header X-Forwarded-Proto $scheme;

            proxy_set_header X-Forwarded-Port $server_port;

            proxy_set_header X-Forwarded-Host $server_name;

            # Alternative configuration to ensure links are updated for the clients access point (not required if ‘USE_FORWARD_HEADERS=true’)

            # is enabled in conf/environment.(sh|bat).

            #proxy_redirect http://$server_name/ https://$server_name:$server_port/;

            #proxy_redirect http://$server_name:$proxy_port/ https://$server_name:$server_port/;

Web Socket Upgrade #

This section is important so that Web Sockets are used and edgeSuite does not fallback to sockjs which will slow down the communication with edgeSuite clients:

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection “upgrade”;
proxy_set_header Origin ”;
proxy_read_timeout 300;

Additional Configuration Options #

The sample configurations do not cover load balancing. If you are using upstream to map multiple backends, then you will need to consider options to apply sticky session handling. Sticky session ensures that a session stays mapped to a single backend server unless there is a connection failure and the client must be redirected to another backend server.