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/controlapi/"> <meta property="og:title" content="NGINX Unit: Control API"> <meta content="Learn the basics of Unit's control API." name="og:description" /> <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="Configuration" href="../configuration/" /> <link rel="prev" title="Installation" href="../installation/" /> <title>Control API — 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 current"><a class="current reference internal" href="#">Control API</a><ul> <li class="toctree-l2"><a class="reference internal" href="#openapi-specification">OpenAPI specification</a></li> <li class="toctree-l2"><a class="reference internal" href="#quick-start">Quick start</a></li> <li class="toctree-l2"><a class="reference internal" href="#api-manipulation">API manipulation</a></li> <li class="toctree-l2"><a class="reference internal" href="#examples">Examples</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="../configuration/">Configuration</a></li> <li class="toctree-l1"><a class="reference internal" href="../scripting/">Scripting</a></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="control-api"> <h1>Control API<a class="headerlink" href="#control-api" title="Permalink to this heading">§</a></h1> Unit’s configuration is JSON-based, accessible via a RESTful control API, and entirely manageable over HTTP. The control API provides a root object (/) that comprises four primary options: <table border="1" class="docutils align-default"> <colgroup> <col width="50%" /> <col width="50%" /> </colgroup> <thead valign="bottom"> <tr class="row-odd"><th class="head">Object</th> <th class="head">Description</th> </tr> </thead> <tbody valign="top"> <tr class="row-even"><td>/certificates</td> <td>Responsible for SSL/TLS <a class="reference internal" href="../certificates/">certificate management</a>.</td> </tr> <tr class="row-odd"><td>/config</td> <td>Used for general <a class="reference internal" href="../configuration/">configuration management</a>.</td> </tr> <tr class="row-even"><td>/control</td> <td>Queried for <a class="reference internal" href="../configuration/#configuration-proc-mgmt">application restart</a>.</td> </tr> <tr class="row-odd"><td>/status</td> <td>Queried for <a class="reference internal" href="../statusapi/">usage statistics</a>.</td> </tr> </tbody> </table> The API is exposed through a socket whose type and address depend on the <a class="reference internal" href="../installation/">installation method</a>. Its compile-time setting can be overridden at <a class="reference internal" href="../howto/source/#source-startup">startup</a>. For consistency and <a class="reference internal" href="../howto/security/#security-socket-state">security</a>, our examples use Unix domain sockets unless stated otherwise. Example queries use curl, and URIs are prefixed with http://localhost as the utility expects (the hostname is irrelevant for Unit itself), but you can use any HTTP tool you like. For instance, Visual Studio Code users may benefit from this <a class="reference external" href="https://marketplace.visualstudio.com/items?itemName=Stanislav.vscode-nginx-unit">third-party extension</a>. <details id=no-config-files_ onclick="window.location.hash='#no-config-files'"> <summary>No configuration files used</summary><div class="docutils container"> The control API is the single source of truth about Unit’s configuration. There are no configuration files that can or should be manipulated; this is a deliberate design choice made to avoid issues such as: <ul class="simple"> <li>Undetected invalid states: Configuration files can be saved in an invalid state, and the issue won’t be seen until reload or startup. The control API avoids this by validating configuration changes on the fly.</li> <li>Too broad or too narrow configuration file permissions: If a configuration file is inaccessible, it can’t be loaded; if it’s public, sensitive data may leak. The control API has a single manageable point of entry.</li> <li>Unpredictable behavior: In a configuration file hierarchy, it’s easy to lose track and misconfigure something. With the control API, the entire configuration is a single, organized, and navigatable entity.</li> </ul> </div> </details><details id=conf-replication_ onclick="window.location.hash='#conf-replication'"> <summary>Replicating Unit states</summary><div class="docutils container"> Although Unit is fully dynamic, sometimes you just want to copy an existing setup without extra modification. Unit’s <a class="reference internal" href="../howto/source/#source-config-src-state">state directories</a> are interchangeable as long as Unit version stays the same, so you can use a shortcut to replicate a Unit instance. Also, this works with the Docker <a class="reference internal" href="../howto/docker/">images</a>. <div class="admonition warning"> Warning Unit’s state can change its structure between versions and must not be edited by external means. </div> On the machine where the reference Unit instance runs, find out where the state is stored: <div class="highlight-console notranslate"><div class="highlight"><pre>$ unitd -h --state DIRECTORY set state directory name default: "/path/to/reference/unit/state" </pre></div> </div> Double-check that the state location isn’t overridden at startup: <div class="highlight-console notranslate"><div class="highlight"><pre>$ ps ax | grep unitd ... unit: main v1.34.2 [unitd --state /runtime/path/to/reference/unit/state ... ] </pre></div> </div> Repeat these commands on the second machine to see where the target instance stores its state. Stop both Unit instances, for example, running the following command as root: <div class="highlight-console notranslate"><div class="highlight"><pre># systemctl stop unit </pre></div> </div> <div class="admonition note"> Note Stop and start commands may differ if Unit was installed from a <a class="reference internal" href="../installation/#installation-community-repos">non-official</a> repo or built from <a class="reference internal" href="../installation/#source">source</a>. </div> Copy the reference state directory to the target state directory by arbitrary means; make sure to include subdirectories and hidden files. Finally, restart both Unit instances running the following command as root: <div class="highlight-console notranslate"><div class="highlight"><pre># systemctl restart unit </pre></div> </div> If you run your Unit instances manually, --state can be used to set the state directory at <a class="reference internal" href="../howto/source/#source-startup">startup</a>. After restart, the target instance picks up the configuration you’ve copied to the state directory. </div> </details><div class="section" id="openapi-specification"> <h2>OpenAPI specification<a class="headerlink" href="#openapi-specification" title="Permalink to this heading">§</a></h2> <blockquote> <div>For a more formal approach to Unit’s control API, download the <a class="reference external" href="https://raw.githubusercontent.com/nginx/unit/master/docs/unit-openapi.yaml">OpenAPI specification</a> or try the interactive Docker <a class="reference download internal" download="" href="../_downloads/b16e6c96d59a63357f36a3f0c11bf14c/unit-openapi.Dockerfile"><code class="xref download docutils literal notranslate">version</code></a>. First, build the image and run a container: <div class="highlight-console notranslate"><div class="highlight"><pre>$ docker build --tag=unit-openapi -f unit-openapi.Dockerfile . </pre></div> </div> <div class="highlight-console notranslate"><div class="highlight"><pre>$ docker run -d -p 8765:8765 -p 8080:8080 unit-openapi </pre></div> </div> Next, open http://localhost:8765 in a browser. To use this image against a pre-existing Unit instance, type in the address and port of the instance’s <a class="reference internal" href="#configuration-socket">control socket</a> (only IP sockets are supported now) on the page: <a class="reference internal image-reference" href="../_images/openapi.png"><img alt="Unit's OpenAPI Image Page - Customizing Control Socket Address" src="../_images/openapi.png" style="width: 100%;" /></a> </div></blockquote> </div> <div class="section" id="quick-start"> <h2>Quick start<a class="headerlink" href="#quick-start" title="Permalink to this heading">§</a></h2> <div class="admonition note"> Note Run the <cite>curl</cite> commands in this section as root. </div> For a brief intro, we configure Unit to serve a static file. Suppose you saved this as /www/data/index.html: <div class="highlight-html notranslate"><div class="highlight"><pre><!DOCTYPE html> <html> <head> <title>Welcome to NGINX Unit!</title> <style> body { width: 35em; margin: 0 auto; font-family: Tahoma, Verdana, Arial, sans-serif; } </style> </head> <body> <h1>Welcome to NGINX Unit!</h1> <p>If you see this page, the NGINX Unit web server is successfully installed and working. Further configuration is required. </p> <p>For online documentation and support, please refer to <a href="https://unit.nginx.org/">unit.nginx.org</a>.<br/> </p> <p><em>Thank you for using NGINX Unit.</em></p> </body> </html> </pre></div> </div> Now, Unit should <a class="reference internal" href="../configuration/#configuration-listeners">listen</a> on a port that <a class="reference internal" href="../configuration/#configuration-routes">routes</a> the incoming requests to a share action, which serves the file: <div class="highlight-json notranslate"><div class="highlight"><pre>{ "listeners": { "127.0.0.1:8080": { "pass": "routes" } }, "routes": [ { "action": { "share": "/www/data$uri" } } ] } </pre></div> </div> To configure Unit, PUT this snippet to the /config section via the <a class="reference internal" href="../howto/source/#source-startup">control socket</a>. Working with JSON in the command line can be cumbersome; instead, save and upload it as snippet.json. <div class="highlight-console notranslate"><div class="highlight"><pre># curl -X PUT --data-binary @snippet.json --unix-socket \ /path/to/control.unit.sock http://localhost/config { "success": "Reconfiguration done." } </pre></div> </div> To confirm this works, query the listener. Unit responds with the index.html file from the share directory: <div class="highlight-console notranslate"><div class="highlight"><pre>$ curl -i 127.0.0.1:8080 HTTP/1.1 200 OK Content-Type: text/html Server: Unit/1.28.0 <!DOCTYPE html> <html> <head> <title>Welcome to NGINX Unit!</title> ... </pre></div> </div> </div> <div class="section" id="api-manipulation"> <h2>API manipulation<a class="headerlink" href="#api-manipulation" title="Permalink to this heading">§</a></h2> To address parts of the control API, query the <a class="reference internal" href="#configuration-socket">control socket</a> over HTTP; URI path segments of your API requests must be the names of its <a class="reference external" href="https://datatracker.ietf.org/doc/html/rfc8259#section-4">JSON object</a> members or indexes of its <a class="reference external" href="https://datatracker.ietf.org/doc/html/rfc8259#section-5">JSON array</a> elements. <div class="admonition note"> Note If you often configure Unit manually, JSON command-line tools such as <a class="reference external" href="https://stedolan.github.io/jq/">jq</a> and <a class="reference external" href="https://jpmens.net/2016/03/05/a-shell-command-to-create-json-jo/">jo</a> may come in handy. </div> The API supports the following HTTP methods: <table border="1" class="docutils align-default"> <colgroup> <col width="50%" /> <col width="50%" /> </colgroup> <thead valign="bottom"> <tr class="row-odd"><th class="head">Method</th> <th class="head">Action</th> </tr> </thead> <tbody valign="top"> <tr class="row-even"><td>GET</td> <td>Returns the entity at the request URI as a JSON value in the HTTP response body.</td> </tr> <tr class="row-odd"><td>POST</td> <td>Updates the array at the request URI, appending the JSON value from the HTTP request body.</td> </tr> <tr class="row-even"><td>PUT</td> <td>Replaces the entity at the request URI and returns a status message in the HTTP response body.</td> </tr> <tr class="row-odd"><td>DELETE</td> <td>Deletes the entity at the request URI and returns a status message in the HTTP response body.</td> </tr> </tbody> </table> Before a change, Unit checks the difference it makes in the entire configuration; if there’s none, nothing is done. Thus, you can’t restart an app by reuploading its unchanged configuration (but there’s a <a class="reference internal" href="../configuration/#configuration-proc-mgmt">way</a> of restarting apps). Unit performs actual reconfiguration steps as gracefully as possible: running tasks expire naturally, connections are properly closed, processes end smoothly. Any type of update can be done with different URIs, provided you supply the right JSON. Run the following commands as root: <div class="highlight-console notranslate"><div class="highlight"><pre># curl -X PUT -d '{ "pass": "applications/blogs" }' --unix-socket \ /path/to/control.unit.sock http://localhost/config/listeners/127.0.0.1:8300 </pre></div> </div> <div class="highlight-console notranslate"><div class="highlight"><pre># curl -X PUT -d '"applications/blogs"' --unix-socket /path/to/control.unit.sock \ http://localhost/config/listeners/127.0.0.1:8300/pass </pre></div> </div> However, the first command replaces the entire listener, dropping any other options you could have configured, whereas the second one replaces only the pass value and leaves other options intact. </div> <div class="section" id="examples"> <h2>Examples<a class="headerlink" href="#examples" title="Permalink to this heading">§</a></h2> To minimize typos and effort, avoid embedding JSON payload in your commands; instead, store your configuration snippets for review and reuse. For instance, save your application object as wiki.json: <div class="highlight-json notranslate"><div class="highlight"><pre>{ "type": "python", "module": "wsgi", "user": "www-wiki", "group": "www-wiki", "path": "/www/wiki/" } </pre></div> </div> Use it to set up an application called wiki-prod. <div class="highlight-console notranslate"><div class="highlight"><pre># curl -X PUT --data-binary @wiki.json \ --unix-socket /path/to/control.unit.sock http://localhost/config/applications/wiki-prod </pre></div> </div> Use it again to set up a development version of the same app called wiki-dev: <div class="highlight-console notranslate"><div class="highlight"><pre># curl -X PUT --data-binary @wiki.json \ --unix-socket /path/to/control.unit.sock http://localhost/config/applications/wiki-dev </pre></div> </div> Toggle the wiki-dev app to another source code directory: <div class="highlight-console notranslate"><div class="highlight"><pre># curl -X PUT -d '"/www/wiki-dev/"' \ --unix-socket /path/to/control.unit.sock http://localhost/config/applications/wiki-dev/path </pre></div> </div> Next, boost the process count for the production app to warm it up a bit: <div class="highlight-console notranslate"><div class="highlight"><pre># curl -X PUT -d '5' \ --unix-socket /path/to/control.unit.sock http://localhost/config/applications/wiki-prod/processes </pre></div> </div> Add a listener for the wiki-prod app to accept requests at all host IPs: <div class="highlight-console notranslate"><div class="highlight"><pre># curl -X PUT -d '{ "pass": "applications/wiki-prod" }' \ --unix-socket /path/to/control.unit.sock 'http://localhost/config/listeners/*:8400' </pre></div> </div> Plug the wiki-dev app into the listener to test it: <div class="highlight-console notranslate"><div class="highlight"><pre># curl -X PUT -d '"applications/wiki-dev"' --unix-socket /path/to/control.unit.sock \ 'http://localhost/config/listeners/*:8400/pass' </pre></div> </div> Then rewire the listener, adding a URI-based route to the development version of the app: <div class="highlight-console notranslate"><div class="highlight"><pre>$ cat << EOF > config.json [ { "match": { "uri": "/dev/*" }, "action": { "pass": "applications/wiki-dev" } } ] EOF </pre></div> </div> <div class="highlight-console notranslate"><div class="highlight"><pre># curl -X PUT --data-binary @config.json --unix-socket \ /path/to/control.unit.sock http://localhost/config/routes </pre></div> </div> <div class="highlight-console notranslate"><div class="highlight"><pre># curl -X PUT -d '"routes"' --unix-socket \ /path/to/control.unit.sock 'http://localhost/config/listeners/*:8400/pass' </pre></div> </div> Next, change the wiki-dev’s URI prefix in the routes array, using its index (0): <div class="highlight-console notranslate"><div class="highlight"><pre># curl -X PUT -d '"/development/*"' --unix-socket /path/to/control.unit.sock \ http://localhost/config/routes/0/match/uri </pre></div> </div> Append a route to the prod app: POST always adds to the array end, so there’s no need for an index: <div class="highlight-console notranslate"><div class="highlight"><pre># curl -X POST -d '{"match": {"uri": "/production/*"}, \ "action": {"pass": "applications/wiki-prod"}}' \ --unix-socket /path/to/control.unit.sock \ http://localhost/config/routes/ </pre></div> </div> Otherwise, use PUT with the array’s last index (0 in our sample) plus one to add the new item at the end: <div class="highlight-console notranslate"><div class="highlight"><pre># curl -X PUT -d '{"match": {"uri": "/production/*"}, \ "action": {"pass": "applications/wiki-prod"}}' \ --unix-socket /path/to/control.unit.sock \ http://localhost/config/routes/1/ </pre></div> </div> To get the complete /config section: <div class="highlight-console notranslate"><div class="highlight"><pre># curl --unix-socket /path/to/control.unit.sock http://localhost/config/ { "listeners": { "*:8400": { "pass": "routes" } }, "applications": { "wiki-dev": { "type": "python", "module": "wsgi", "user": "www-wiki", "group": "www-wiki", "path": "/www/wiki-dev/" }, "wiki-prod": { "type": "python", "processes": 5, "module": "wsgi", "user": "www-wiki", "group": "www-wiki", "path": "/www/wiki/" } }, "routes": [ { "match": { "uri": "/development/*" }, "action": { "pass": "applications/wiki-dev" } }, { "action": { "pass": "applications/wiki-prod" } } ] } </pre></div> </div> To obtain the wiki-dev application object: <div class="highlight-console notranslate"><div class="highlight"><pre># curl --unix-socket /path/to/control.unit.sock \ http://localhost/config/applications/wiki-dev { "type": "python", "module": "wsgi", "user": "www-wiki", "group": "www-wiki", "path": "/www/wiki-dev/" } </pre></div> </div> You can save JSON returned by such requests as .json files for update or review: <div class="highlight-console notranslate"><div class="highlight"><pre># curl --unix-socket /path/to/control.unit.sock \ http://localhost/config/ > config.json </pre></div> </div> To drop the listener on *:8400: <div class="highlight-console notranslate"><div class="highlight"><pre># curl -X DELETE --unix-socket /path/to/control.unit.sock \ 'http://localhost/config/listeners/*:8400' </pre></div> </div> Mind that you can’t delete objects that other objects rely on, such as a route still referenced by a listener: <div class="highlight-console notranslate"><div class="highlight"><pre># curl -X DELETE --unix-socket /path/to/control.unit.sock \ http://localhost/config/routes { "error": "Invalid configuration.", "detail": "Request \"pass\" points to invalid location \"routes\"." } </pre></div> </div> </div> </div> <div class="nxt_edit_link"><a href="https://github.com/nginx/unit-docs/edit/main/source/controlapi.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>