Scripting§

NGINX Unit’s control API supports JavaScript expressions, including function calls, in the form of template literals written in the njs dialect of JavaScript. They can be used with these configuration options:

• pass in listeners and actions to choose between routes, applications, app targets, or upstreams.

• response_headers values in actions to manipulate response header fields.

• rewrite in actions to enable URI rewriting.

• share and chroot in actions to control static content serving.

• location in return actions to enable HTTP redirects.

• format in the access log to customize Unit’s log output.

As its JavaScript engine, Unit uses the njs library, shipped with the official packages or built from source.

Some request properties are exposed as njs objects or scalars:

Template lterals are wrapped in backticks. To use a literal backtick in a string, escape it: \\` (escaping backslashes is a JSON requirement). The njs snippets should be enclosed in curly brackets: ${...}.

Next, you can upload and use custom JavaScript modules with your configuration. Consider this http.js script that distinguishes requests by their Authorization header field values:

var http = {}

http.route = function(headers) {
    var authorization = headers['Authorization'];
    if (authorization) {
        var user = atob(authorization.split(' ')[1]);
        if (String(user) == 'user:password') {
            return 'accept';
        }

        return 'forbidden';
    }

    return 'unauthorized';
}

export default http

To upload it to Unit’s JavaScript module storage as http:

# curl -X PUT --data-binary @http.js --unix-socket /path/to/control.unit.sock \
      http://localhost/js_modules/http

Unit doesn’t enable the uploaded modules by default, so add the module’s name to settings/js_module:

# curl -X PUT -d '"http"' /path/to/control.unit.sock \
      http://localhost/config/settings/js_module

Now, the http.route() function can be used with Unit-supplied header field values:

{
    "routes": {
        "entry": [
            {
                "action": {
                    "pass": "routes/`${http.route(headers)}`"
                }
            }
        ],

        "unauthorized": [
            {
                "action": {
                    "return": 401
                }
            }
        ],

        "forbidden": [
            {
                "action": {
                    "return": 403
                }
            }
        ],

        "accept": [
            {
                "action": {
                    "return": 204
                }
            }
        ]
    }
}

"routes": {
    "parse": [
        {
            "action": {
                "pass": "`routes/${ headers['User-Agent'].split('/')[0] == 'curl' ? 'reject' : 'default' }`"
            }
        }
    ],

    "reject": [
        {
            "action": {
                "return": 400
            }
        }
    ],

    "default": [
        {
            "action": {
                "return": 204
            }
        }
    ]
}

{
    "path": "/var/log/unit/access_kv.log",
    "format": "`@timestamp=${new Date().toISOString()} ip=${remoteAddr} uri=${uri} ${Object.keys(headers).map(k => 'req.' + k + '=\"' + headers[k] + '\"').join(' ')}\n`"
}