{"id":27186,"date":"2018-10-30T06:54:39","date_gmt":"2018-10-29T21:54:39","guid":{"rendered":"https:\/\/jirak.net\/wp\/nginx-unit-now-supports-tls-and-javascript-apps-with-node-js\/"},"modified":"2018-10-30T07:34:38","modified_gmt":"2018-10-29T22:34:38","slug":"nginx-unit-now-supports-tls-and-javascript-apps-with-node-js","status":"publish","type":"post","link":"https:\/\/jirak.net\/wp\/nginx-unit-now-supports-tls-and-javascript-apps-with-node-js\/","title":{"rendered":"NGINX Unit Now Supports TLS and JavaScript Apps with Node.js"},"content":{"rendered":"

NGINX Unit Now Supports TLS and JavaScript Apps with Node.js<\/p>\n

.ngx_blockquote {
\n color: #009639;
\n font-size: 25px;
\n line-height: 35px;
\n font-family: Roboto;
\n font-style: italic;
\n position: relative;
\n padding-left: 30pt;
\n padding-right: 30pt;
\n}<\/p>\n

When our engineering team showed me the initial code for TLS support a few weeks ago, I blocked off a few hours to get through the configuration and set‑up steps. It turned out to be so easy, I finished in about half an hour.<\/p>\n

On September 20, 2018<\/span>, we released NGINX Unit 1.4<\/span>, adding TLS support, certificate storage, and the new \/config<\/strong> URL path for configuration objects. In NGINX Unit 1.5<\/span>, released on October 25, we add support for Node.js applications. Take a look at the complete change list at https:\/\/unit.nginx.org\/CHANGES.txt<\/strong><\/a>.<\/p>\n

In this post we cover the configuration of TLS certificates<\/a> and Node.js applications<\/a> in detail.<\/p>\n

Dynamic Configuration of SSL\/TLS Certificates<\/h2>\n

Security and encryption is a must for every production application. Application connectivity today requires proper and rapid configuration and reconfiguration. For applications of a more dynamic nature, constant changes to their connectivity and security certificates are common.<\/p>\n

NGINX Unit is configured on the fly, without relying on static configuration files and requiring process reloads. Now we extend this philosophy to TLS certificates as well. With NGINX Unit, you can upload certificates, apply them to or remove them from listeners, and replace old certificates – all dynamically, with zero downtime and no changes to the application processes.<\/p>\n

Besides quick and easy configuration, use of TLS with NGINX Unit relieves Go and Node.js engineers from the burden of implementing encryption in the application code itself. Now all apps, including Go and Node.js, can be deployed into a larger production environment faster, more safely, and with no downtime.<\/p>\n

With NGINX Unit, you can add, change, and remove certificates without reloading application processes<\/p>\n

The following example of the initial control API response from NGINX Unit 1.5<\/span> shows that there is now a certificates<\/code> object in addition to the existing configuration structure with listener and application objects:<\/p>\n

curl --unix-socket \/run\/control.unit.sock http:\/\/localhost\/<\/span>\r\n{\r\n      \"certificates\": {},\r\n      \"config\": {\r\n            \"listeners\": {},\r\n            \"applications\": {}\r\n      }\r\n}<\/code><\/pre>\n
Certificates and keys are represented in a different format from other configuration objects in the API: we upload them to the certificate store in PEM format as the body of a PUT<\/code> request.<\/p>\n
You upload certificates and keys to the certificate store in PEM format as the body of a PUT request<\/p>\n
Generating a Certificate<\/h3>\n
To try this out with a simple self‑signed certificate, we first run this command to generate one:<\/p>\n
openssl req -x509 -subj \/CN=localhost -days 365 -set_serial 2 -newkey rsa:4096 -keyout cert.key -nodes -out cert.pem<\/span><\/code><\/pre>\n
Notice that we placed the certificate and the key in separate files. Let\u2019s combine them:<\/p>\n
cat cert.key cert.pem > chain.pem<\/span><\/code><\/pre>\n
For a production environment, it’s a best practice to obtain a full certificate chain from a provider such as Let’s Encrypt<\/a>. The resulting file looks similar to this:<\/p>\n
-----BEGIN CERTIFICATE-----\r\nMIIDHDCCAgQCCQCVgasbCyT1BjANBgkqhkiG9w0BAQsFADBQMQswCQYDVQQGEwJV\r\n...\r\nvyYJp0qUWRWeYm1CTZaudpR74cZVhz\/RKGFfXkK2bD6Vv8uHI0hbK0p3KlKZ333j\r\nkMSJ9yD+dF9quUbvS9yJUEHcF+96ZcmFVGRnwvnwXUE=\r\n-----END CERTIFICATE-----\r\n-----BEGIN RSA PRIVATE KEY-----\r\nMIIEpAIBAAKCAQEAqb8VkMnAKqqIERHwNklelCE6gzfMd99yX+YoeerB9QVKZkx\/\r\n...\r\nqhtqYRlezYQOUbMGAsREtKqZCn+urL8Bql2IbPQ9vwSfioxNUNyHod+2E\/JDoEF8\r\nOzsBSkR8H7NcSaHCbZCMKtIvGZGM4ODRqP484\/KiXpqjhq8BOtTKJA==\r\n-----END RSA PRIVATE KEY-----<\/code><\/pre>\n
If we have intermediate certificates or a CA certificate (or both), we concatenate them with the certificate and key as well.<\/p>\n
Uploading a Certificate Chain<\/h3>\n
Then we upload the entire chain via the NGINX Unit API<\/span>. You can use any HTTP tool to upload certificates and update the configuration. Here, we use curl<\/code>:<\/p>\n
curl -X PUT --data-binary @path\/to\/chain.pem --unix-socket \/run\/control.unit.sock 'http:\/\/localhost\/certificates\/mychain'<\/span><\/code><\/pre>\n
This creates a new chain that we can check out at the \/certificates\/mychain<\/strong> URL path. In our self‑signed certificate example, the configuration looks like this:<\/p>\n
{\r\n      \"key\": \"RSA (4096 bits)\",\r\n      \"chain\": [\r\n            {\r\n                  \"subject\": {\r\n                        \"common_name\": \"localhost\"\r\n                  },\r\n\r\n                  \"issuer\": {\r\n                        \"common_name\": \"localhost\"\r\n                  },\r\n\r\n                  \"validity\": {\r\n                        \"since\": \"Oct 25 18:59:18 2018 GMT\",\r\n                        \"until\": \"Oct 25 18:59:18 2019 GMT\"\r\n                  }\r\n            }\r\n      ]\r\n}<\/code><\/pre>\n
Applying the Certificate to a Listener<\/h3>\n
Now we apply the newly created certificate to a listener – either an existing one or one created by the command – by including a tls<\/code> object with the certificate<\/code> parameter in the listener’s configuration:<\/p>\n
curl -X PUT --data-binary '{\"application\":\"myapp\",\"tls\":{\"certificate\":\"mychain\"}}' --unix-socket \/run\/control.unit.sock 'http:\/\/localhost\/config\/listeners\/*:8043'<\/span><\/code><\/pre>\n
A listener configuration with the new tls<\/code> object results:<\/p>\n
\"*:8043\": {\r\n      \"application\": \"myapp\",\r\n      \"tls\": {\r\n            \"certificate\":\"mychain\"\r\n      }\r\n}<\/code><\/pre>\n
To summarize, the full configuration of a TLS‑enabled application is as follows:<\/p>\n
{\r\n      \"certificates\": {\r\n            \"mychain\": {\r\n                  \"key\": \"RSA (4096 bits)\",\r\n                  \"chain\": [\r\n                        {\r\n                              \"subject\": {\r\n                                    \"common_name\": \"localhost\"\r\n                              },\r\n\r\n                              \"issuer\": {\r\n                                    \"common_name\": \"localhost\"\r\n                              },\r\n\r\n                              \"validity\": {\r\n                                    \"since\": \"Oct 25 18:59:18 2018 GMT\",\r\n                                    \"until\": \"Oct 25 18:59:18 2019 GMT\"\r\n                              }\r\n                        }\r\n                  ]\r\n            }\r\n      },\r\n\r\n      \"config\": {\r\n            \"settings\": {},\r\n            \"listeners\": {\r\n                  \"*:8043\": {\r\n                        \"application\": \"myapp\",\r\n                        \"tls\": {\r\n                              \"certificate\":\"mychain\"\r\n                        }\r\n\r\n                  }\r\n            },\r\n\r\n            \"applications\": {\r\n                  \"myapp\": {\r\n                        \"type\": \"php\",\r\n                        \"root\": \"\/path\/to\/php\",\r\n                        \"script\": \"index.php\"\r\n                  }\r\n            }\r\n      }\r\n}<\/code><\/pre>\n
Learn more about configuring TLS with NGINX Unit at https:\/\/unit.nginx.org\/configuration\/#ssl-tls-and-certificates<\/strong><\/a>.<\/p>\n
Support for Node.js Applications<\/h2>\n
NGINX Unit 1.5<\/span> adds Node.js (JavaScript) to the set of languages we support.<\/p>\n
Node.js and Go apps are similar in that you essentially create your own server when you build an application. The application is launched as a separate process – either directly or through a process manager. <\/p>\n
In many environments, NGINX (or another load balancer) is placed in front of Node.js and Go apps.  This additional software often complicates the environment. With NGINX Unit, you can configure this functionality using just one software server through one consistent and easy‑to‑use API.<\/p>\n
Here are two examples, in Go and Node.js respectively:<\/p>\n
http.ListenAndServe(\":8000\", nil)<\/code><\/pre>\n
var http = require('http');\r\nhttp.createServer(function (req, res) {\r\n\/\/ ...\r\n}).listen(8080);<\/code><\/pre>\n
Installing the unit‑http<\/code> Package<\/h3>\n
To run a Node.js application in NGINX Unit, we add a special package (module) so the external runtime can communicate with NGINX Unit’s router process instead of listening on a port directly. NGINX Unit launches the app and communicates with it through shared memory. To reflect this difference from other app types, we have elevated our concept of these apps to a higher level, referring to them as \"type\":<\/code> \"external\"<\/code><\/span>.<\/p>\n
For Node.js, the relevant package is called unit-http<\/span>, and it’s now available on NPM at https:\/\/www.npmjs.com\/package\/unit-http<\/strong><\/a>.<\/p>\n
After installing NGINX Unit, we first install the prerequisite unit-dev<\/span> package (the command shown is for Debian and Ubuntu systems), and then use NPM to install the unit-http<\/span> package:<\/p>\n
apt-get install unit-dev\r\nnpm install unit-http<\/span><\/code><\/pre>\n
We then make two changes to the code for our Node.js app:<\/p>\n