Edge Technologies, Inc. | Documentation | Configuring NGINX for SSL Termination

Overview

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 edgeCore administrator get NGINX configured in front of an edgeCore instance.

Installation of NGINX

Please follow NGINX’s official documentation for installing on this link.
It provides options for installing NGINX OpenSource or NGINX Plus.
The following is a good tutorial of NGINX and its features/configuration is found on this link.

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.

edgeCore Configuration (added in version 3.9.2+)

edgeCore 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, edgeCore 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;
worker_rlimit_nofile 8192;
events {
worker_connections 4096; ## Default: 1024
}

Upstream Backends (optional)

The following upstream edgeCore 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 127.0.0.1:8080; #if edge works on HTTP
}
upstream edgesuite {
      server 127.0.0.1:8443; #if edge works on HTTPS
}

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 edgeCore 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 edgeCore does not fallback to sockjs which will slow down the communication with edgeCore 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.

Web App Config Sample

upstream edgesuite {
        server 127.0.0.1:8443;
}
server {
        listen       80;
        server_name  your-domain.com;
        root         /var/www/html;
        return 301 https://your-domain.com$request_uri;
}
server {
        listen       443 ssl http2;
        server_name  your-domain.com;
        root         /var/www/html/;
        ssl_certificate "/etc/letsencrypt/live/path-to-fullchain/fullchain.pem";
        ssl_certificate_key "/etc/letsencrypt/live/path-to-privkey/privkey.pem";
#### (In this case we use let's encrypt)
        ssl_session_cache shared:SSL:1m;
        ssl_session_timeout  10m;
        ssl_ciphers HIGH:!aNULL:!MD5;
        ssl_prefer_server_ciphers on;
        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;
        location / {
        proxy_pass https://127.0.0.1:8443;
        proxy_set_header Host $host:$server_port;
        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;
}
}