CINXE.COM

<!DOCTYPE html> <html> <head>  <script async="async" src="https://consent.trustarc.com/notice?domain=f5.com&c=teconsent&js=nj&noticeType=bb&text=true&gtm=1" crossorigin=""></script>  <script src="https://mktg.tags.f5.com/nginx-unit/prod/utag.sync.js"></script>  <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" />  <meta property="og:type" content="website"> <meta property="og:url" content="https://unit.nginx.org/scripting/"> <meta property="og:title" content="NGINX Unit: Scripting"> <meta property="og:image" content="http://unit.nginx.org/_static/logo.png?e39b3bbae06cd8bdb5a7814270161b52"> <meta property="og:image:secure_url" content="https://unit.nginx.org/_static/logo.png?e39b3bbae06cd8bdb5a7814270161b52"> <meta property="og:image:width" content="988"> <meta property="og:image:height" content="357"> <meta property="og:image:alt" content="NGINX Unit logo" />  <meta property="twitter:card" content="summary_large_image"> <style> /* open-sans-regular - latin_latin-ext */ @font-face { font-display: swap; font-family: 'Open Sans'; font-style: normal; font-weight: 400; src: local('OpenSans'), local('Open Sans'), local('Open Sans Regular'), local('OpenSans-Regular'), url('../_static/open-sans-v40-latin_latin-ext-regular.woff2?058e68d126ca347a4db54933db4738db') format('woff2'); } /* open-sans-italic - latin_latin-ext */ @font-face { font-display: swap; font-family: 'Open Sans'; font-style: italic; font-weight: 400; src: local('OpenSansItalic'), local('Open Sans Italic'), local('OpenSans Italic'), local('OpenSans-Italic'), url('../_static/open-sans-v40-latin_latin-ext-italic.woff2?86b58c2ae26455092651312b8582674f') format('woff2'); } /* open-sans-700 - latin_latin-ext */ @font-face { font-display: swap; font-family: 'Open Sans'; font-style: normal; font-weight: 700; src: local('OpenSansBold'), local('Open Sans Bold'), local('OpenSans Bold'), local('OpenSans-Bold'), url('../_static/open-sans-v40-latin_latin-ext-700.woff2?40654e941d643aead74c5d6a56a38c6b') format('woff2'); } /* open-sans-700italic - latin_latin-ext */ @font-face { font-display: swap; font-family: 'Open Sans'; font-style: italic; font-weight: 700; src: local('OpenSansBoldItalic'), local('Open Sans Bold Italic'), local('OpenSans Bold Italic'), local('OpenSans-BoldItalic'), local('OpenSans-Bold-Italic'), url('../_static/open-sans-v40-latin_latin-ext-700italic.woff2?e4fada57efe79e0fb447a7dc076a568b') format('woff2'); } </style> <link rel="stylesheet" href="../_static/style.css?02b1052daea25a810283ecaa29bc2462" /> <link rel="icon" href="../_static/icon.png?26255dfe9094cf47412c8b5d3757467b" /> <link rel="alternate" type="application/rss+xml" title="Subscribe to NGINX Unit News" href="https://unit.nginx.org/rss.xml" /> <script async src="../_static/script.js?8dc8ff30c396ce882326156b1581000a"></script> <link rel="next" title="SSL/TLS certificates" href="../certificates/" /> <link rel="prev" title="Configuration" href="../configuration/" /> <title>Scripting — NGINX Unit</title> </head> <body>  <script type="text/javascript"> (function(a,b,c,d) { a='//mktg.tags.f5.com/nginx-unit/prod/utag.js'; b=document;c='script';d=b.createElement(c);d.src=a; d.type='text/java'+c;d.async=true; a=b.getElementsByTagName(c)[0];a.parentNode.insertBefore(d,a)})(); </script>   <div id="main"> <div id="side"> <h1> <a href="../"> <img src="../_static/logo.svg?ea753eb2210f855447af3b2367898f85" alt="NGINX Unit" /> </a> <div id="version_link" title="Released on Feb 26, 2025"> <a style="text-decoration:none;" href="../news/2025/unit-1.34.2-released/">v. 1.34.2</a> </div> </h1> <ul class="current"> <li class="toctree-l1"><a class="reference internal" href="../">About</a></li> <li class="toctree-l1"><a class="reference internal" href="../keyfeatures/">Key features</a></li> <li class="toctree-l1"><a class="reference internal" href="../news/">News</a></li> <li class="toctree-l1"><a class="reference internal" href="../installation/">Installation</a></li> <li class="toctree-l1"><a class="reference internal" href="../controlapi/">Control API</a></li> <li class="toctree-l1"><a class="reference internal" href="../configuration/">Configuration</a></li> <li class="toctree-l1 current"><a class="current reference internal" href="#">Scripting</a><ul> <li class="toctree-l2"><a class="reference internal" href="#examples">Examples</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="../certificates/">SSL/TLS certificates</a></li> <li class="toctree-l1"><a class="reference internal" href="../statusapi/">Status API</a></li> <li class="toctree-l1"><a class="reference internal" href="../unitctl/">CLI (unitctl)</a></li> <li class="toctree-l1"><a class="reference internal" href="../howto/">How-to</a></li> <li class="toctree-l1"><a class="reference internal" href="../troubleshooting/">Troubleshooting</a></li> <li class="toctree-l1"><a class="reference internal" href="../community/">Community</a></li> </ul> </div> <div id="content"> <div class="section" id="scripting"> <h1>Scripting<a class="headerlink" href="#scripting" title="Permalink to this heading">§</a></h1> NGINX Unit’s <a class="reference internal" href="../controlapi/">control API</a> supports JavaScript expressions, including function calls, in the form of <a class="reference external" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals">template literals</a> written in <a class="reference external" href="https://nginx.org/en/docs/njs/">NGINX JavaScript</a> ( njs ). They can be used with these <a class="reference internal" href="../configuration/">configuration</a> options: <ul class="simple"> <li>pass in <a class="reference internal" href="../configuration/#configuration-listeners">listeners</a> and <a class="reference internal" href="../configuration/#configuration-routes-action">actions</a> to choose between routes, applications, app targets, or upstreams.</li> <li>response_headers values in <a class="reference internal" href="../configuration/#configuration-routes-action">actions</a> to manipulate response header fields.</li> <li>rewrite in <a class="reference internal" href="../configuration/#configuration-routes-action">actions</a> to enable <a class="reference internal" href="../configuration/#configuration-rewrite">URI rewriting</a>.</li> <li>share and chroot in <a class="reference internal" href="../configuration/#configuration-routes-action">actions</a> to control <a class="reference internal" href="../configuration/#configuration-static">static content serving</a>.</li> <li>location in return <a class="reference internal" href="../configuration/#configuration-return">actions</a> to enable HTTP redirects.</li> <li>format in the <a class="reference internal" href="../configuration/#custom-log-format">access log</a> to customize Unit’s log output.</li> <li>if in the <a class="reference internal" href="../configuration/#id2">access log</a> to dynamically turn Unit’s logging on and off.</li> </ul> As its JavaScript engine, Unit uses the njs library, shipped with the <a class="reference internal" href="../installation/#installation-precomp-pkgs">official packages</a> or <a class="reference internal" href="../howto/source/#source-njs">built from source</a>. <div class="admonition warning"> Warning Unit 1.32.0 and later require <a class="reference external" href="https://nginx.org/en/docs/njs/changes.html">njs 0.8.2</a>. </div> Some request properties are exposed as njs objects or scalars: <table border="1" class="docutils align-default"> <colgroup> <col width="33%" /> <col width="33%" /> <col width="33%" /> </colgroup> <thead valign="bottom"> <tr class="row-odd"><th class="head">Name</th> <th class="head">Type</th> <th class="head">Description</th> </tr> </thead> <tbody valign="top"> <tr class="row-even"><td>args</td> <td>Object</td> <td>Query string arguments; Color=Blue is args.Color; can be used with Object.keys().</td> </tr> <tr class="row-odd"><td>cookies</td> <td>Object</td> <td>Request cookies; an authID cookie is cookies.authID; can be used with Object.keys().</td> </tr> <tr class="row-even"><td>headers</td> <td>Object</td> <td>Request header fields; Accept is headers.Accept, Content-Encoding is headers[‘Content-Encoding’] (hyphen requires an array property accessor); can be used with Object.keys().</td> </tr> <tr class="row-odd"><td>host</td> <td>Scalar</td> <td>Host <a class="reference external" href="https://datatracker.ietf.org/doc/html/rfc7230#section-5.4">header field</a>, converted to lower case and normalized by removing the port number and the trailing period (if any).</td> </tr> <tr class="row-even"><td>remoteAddr</td> <td>Scalar</td> <td>Remote IP address of the request.</td> </tr> <tr class="row-odd"><td>uri</td> <td>Scalar</td> <td><a class="reference external" href="https://datatracker.ietf.org/doc/html/rfc7230#section-5.3">Request target</a>, <a class="reference external" href="https://datatracker.ietf.org/doc/html/rfc3986#section-2.1">percent decoded</a> and normalized by removing the <a class="reference external" href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.4">query string</a> and resolving <a class="reference external" href="https://datatracker.ietf.org/doc/html/rfc3986#section-4.2">relative references</a> (“.” and “..”, “//”).</td> </tr> <tr class="row-even"><td>vars</td> <td>Object</td> <td>Unit <a class="reference internal" href="../configuration/#configuration-variables">variables</a>; vars.method is $method.</td> </tr> </tbody> </table> Template literals are wrapped in backticks. To use a literal backtick in a string, escape it: \\` (escaping backslashes is a <a class="reference external" href="https://www.json.org/json-en.html">JSON requirement</a>). 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: <div class="highlight-javascript notranslate"><div class="highlight"><pre>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 </pre></div> </div> To upload it to Unit’s JavaScript module storage as http, run the following command as root: <div class="highlight-console notranslate"><div class="highlight"><pre># curl -X PUT --data-binary @http.js --unix-socket /path/to/control.unit.sock \ http://localhost/js_modules/http </pre></div> </div> Unit doesn’t enable the uploaded modules by default, so add the module’s name to settings/js_module running the following command as root: <div class="highlight-console notranslate"><div class="highlight"><pre># curl -X PUT -d '"http"' /path/to/control.unit.sock \ http://localhost/config/settings/js_module </pre></div> </div> <div class="admonition note"> Note Please note that the js_module option can be a string or an array; choose the appropriate HTTP method. </div> Now, the http.route() function can be used with Unit-supplied header field values: <div class="highlight-json notranslate"><div class="highlight"><pre>{ "routes": { "entry": [ { "action": { "pass": "`routes/${http.route(headers)}`" } } ], "unauthorized": [ { "action": { "return": 401 } } ], "forbidden": [ { "action": { "return": 403 } } ], "accept": [ { "action": { "return": 204 } } ] } } </pre></div> </div> <div class="section" id="examples"> <h2>Examples<a class="headerlink" href="#examples" title="Permalink to this heading">§</a></h2> This example adds simple routing logic that extracts the agent name from the User-Agent header field to reject requests issued by curl: <div class="highlight-json notranslate"><div class="highlight"><pre>"routes": { "parse": [ { "action": { "pass": "`routes/${ headers['User-Agent'].split('/')[0] == 'curl' ? 'reject' : 'default' }`" } } ], "reject": [ { "action": { "return": 400 } } ], "default": [ { "action": { "return": 204 } } ] } </pre></div> </div> This example uses a series of transformations to log the request’s date, IP, URI, and all its headers: <div class="highlight-json notranslate"><div class="highlight"><pre>{ "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`" } </pre></div> </div> The next example will add the Cache-Control Header based on the HTTP Request method: <div class="highlight-json notranslate"><div class="highlight"><pre>{ "action": { "pass": "applications/my_app", "response_headers": { "Cache-Control": "`${vars.method.startsWith('P') ? 'no-cache' : 'max-age=3600'}`" } } } </pre></div> </div> For further reference, see the <a class="reference external" href="https://nginx.org/en/docs/njs/">njs documentation</a>. </div> </div> <div class="nxt_edit_link"><a href="https://github.com/nginx/unit-docs/edit/main/source/scripting.rst"><div></div>Edit this page</a></div> <div class="nxt_discuss_link"><a href="https://github.com/nginx/unit/discussions/"><div></div>Discuss on GitHub</a></div> © 2017-2025 <a href="https://www.nginx.com/">NGINX, Inc.</a>   </div> </div>  <div id="consent_blackbar" style="position:fixed;top:0px;width:100%">  </body> </html>