This is the 3rd post of the series Nginx Manager npm package nginx-upstream. In this blog post, we will see how to define SSL configuration for our Nginx configuration file.

Please checkout the first and second post for convenience. Especially in first post, I am describing the usage of the package in detail.

SSL Termination

SSL termination is one of the best feature for reverse proxies like Nginx. Encryption and decryption processes are heavy CPU consuming jobs and to utilize our backend servers better, we definetly want to offload this operation to a load balancer. On the other hand, we even do not need to host our applications on https since our Nginx can redirect the request decrypted to our backend to our http port.

How to use nginx-upstream to Configure SSL

Below is the two methods to enable and disable SSL configuration.

1
2
3
4
5
6
7
8
9
10
11
12
/**
* Adds certificate information to nginx config file
* @param sitename Sitename alias in nginx config file. Should be unique per nginx server
* @param certificateLocationPath PEM certificate path
* @param callback Calls with error if any
*/
addCertificate(sitename: string, certificateLocationPath: string, callback: (err: any) => void);
/**
* Removes certificate information to nginx config file
* @param callback Calls with error if any
*/
removeCertificate(callback: (err: any) => void);

So to enable certificate in a config file like below;

1
2
3
4
5
6
7
8
9
10
11
12
server {
# Ports
listen 443 ssl;
# Server (FQDN)
server_name example.com;
# SSL Config
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
ssl_ciphers 'AES128+EECDH:AES128+EDH';
ssl_prefer_server_ciphers on;
...
...
}

Use NginxUpstream as below;

1
2
3
4
5
6
7
var tmpTestFile = './test/above.conf';
var nu = new NginxUpstream(tmpTestFile);
nu.addCertificate('testing', '/full/file/path/', function(err){
if(err){
// Handle error.
}
})

Again first parameter refers to our host alias for upstreaming. Second parameter determines where to find our pem file for SSL in our nginx host. We can also define an upload mechanism for your certificate file, but this is out of scope of nginx-upstream since it is dealing with the Nginx config file only.

After executing addCertificate our config file would have 2 new lines and if config file contains return statement for non ssl sites (ie. return 444;), than this line would be removed to enable responding SSL port. An improvement for this method would be getting SSL Config section as a parameter and when adding certificate, adding those lines also.
See below our updated Nginx config file.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
server {
# Ports
listen 443 ssl;
# Server (FQDN)
server_name example.com;
# SSL Config
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
ssl_ciphers 'AES128+EECDH:AES128+EDH';
ssl_prefer_server_ciphers on;
...
...
# Our certificate paths
ssl_certificate /full/file/path/testing.pem;
ssl_certificate_key /full/file/path/testing.key;
}

As you can already guess we can disable SSL for our Nginx with removeCertificate method. Usage is pretty straight forward;

1
2
3
4
5
6
7
var tmpTestFile = './test/above.conf';
var nu = new NginxUpstream(tmpTestFile);
nu.removeCertificate(function(err){
if(err){
// Handle error.
}
})

So we have covered all existing method for NginxUpstream class. I will be adding more fancy functionality on this package for nginx configuration, so keep in touch by commenting below and thanks for reading this far.

Fork me on github to contribute github