NGINX Unit 1.3 Available Now - NGINX


On July 13th we released NGINX Unit 1.3, the latest version of our dynamic multilingual application and web server, with support for more configuration parameters for better fine-tuning your applications. This follows the release of Unit 1.2 on June 7th.

NGINX Unit 1.3 includes these new features:

These new features make your applications more configurable. All parameters can be defined dynamically, without any disruption to running services or loss of connectivity.

Let’s review these features in more detail.

New settings Object

Our plan is to make Unit more configurable. We will add more configuration options for different use cases and various applications. However, for many configuration options, it will make sense to set them globally.

For these cases, we created the object settings, which holds the global configuration options. The initial group of settings supported is related to HTTP connections.

A full example configuration with the settings object follows:

     "settings": {
         "http": {
             "header_read_timeout": 30,
             "body_read_timeout": 30,
             "send_timeout": 30,
             "idle_timeout": 180,
             "max_body_size": 8388608

     "listeners": {
         "": {
             "application": "mercurial",

     "applications": {
         "mercurial": {
             "type": "python 2",
             "module": "hgweb",
             "path": "/data/hg"

There are several methods of configuring a particular configuration parameter:

1. You can update your configuration deployment JSONs and upload the full configuration file through the Unit API into a /config object:

curl -X PUT -d @/path/to/full-config.json --unix-socket /path/to/control.unit.sock http://localhost/config

2. You can create a file or a payload with the settings object names and values, and upload it to /config/settings.

curl -X PUT -d '{"http": { "max_body_size": 8388608} }' --unix-socket /path/to/control.unit.sock http://localhost/config/settings

Note: For any values that you omit from the payload, the default value will be used instead.

3. You can access any of the settings individually and change them with separate HTTP requests.

curl -X PUT -d '8388608' --unix-socket /path/to/control.unit.sock http://localhost/config/settings/max_mody_size

As Unit is a dynamic server, all of these methods apply changes instantly. You don’t have to initiate a service restart or configuration reload action at any point.

HTTP Timeouts

We have included several configuration options for HTTP timeouts.

Note: Timeout values are defined as an integer in seconds. When changing the integer values through the Unit API, do not put them in quotes.

Note: Default values are generally sufficient for most web applications. If your application does not require settings to be changed, leave them at the default values.

Request Body Size Limit

When a client is uploading data, such as form fields, static files, or API payloads through an HTTP connection, all of this data is sent in the request body part of the HTTP request. The length of the request body should be defined in a Content-Length header.

When the request body is larger than the allowed value, Unit responds with HTTP code 413 “Payload too large”.

This configuration parameter has the same meaning as the NGINX directive client_max_body_size. When you limit the request body size in Unit, make sure that your NGINX reverse proxy and load balancers are configured appropriately.

When you want to increase or decrease the limits on the request body, change the /config/settings/max_body_size parameter. The default value is 8MB (8,388,608 bytes).

Note: The value of max_body_size is defined as an integer in bytes. When changing the integer values through the Unit API, do not put them in quotes.

Ansible Integration

The NGINX Ansible role now lets you easily install NGINX Unit and all the Unit packages you may need using Ansible. To install the NGINX Ansible role, run this command:

ansible-galaxy install nginxinc.nginx

You can then create a setup-unit.yml playbook file with the following contents to install Unit and the Unit PHP and Perl modules. This is a sample playbook file for deploying the Ansible Galaxy NGINX role in a localhost to install Unit and the PHP/Perl Unit language packages.

    - hosts: localhost
      become: true
        - role: nginxinc.nginx
        nginx_enable: false
        unit_enable: true
          - unit-php
          - unit-perl

To then run the Ansible playbook, run this command:

ansible-playbook setup-unit.yml

For more examples, check the NGINX Ansible Galaxy homepage , or the NGINX Ansible role repository in Github.

Note: Check the NGINX Unit documentation to see the list of supported modules in your target distribution.


The new features in NGINX Unit 1.3 make it more configurable for your applications. You can define all parameters dynamically, without any disruption to running services, and with no loss of connectivity.

The full changelog for Unit development is available in the source code repositories at,, and on the Unit documentation website:

Watch our code repository on GitHub and join the discussions and development at

If you wish to become a full‑time engineer for NGINX, check our job board.

NGINX Plus subscribers get NGINX Unit support at no additional charge. Download a free 30-day trial of NGINX Plus today!

Retrieved by Nick Shadrin from website.