隆重推出 NGINX Unit 1.3

Nick Shadrin of F5

Software Architect

2018-07-13

On July 13 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 NGINX Unit 1.2 on June 7.

NGINX Unit 1.3 includes these new features:

• New settings object in the configuration API
• Configuration of HTTP timeouts
• Configuration of request body size limit
• Automatic use of Bundler for Ruby applications
• Ansible integration

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 NGINX Unit more configurable. We will add more configuration options for different use cases and various applications. However, for many configuration options, it makse 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": {
         "127.0.0.1:8034": {
             "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 NGINX Unit is a dynamic server, all of these methods apply changes instantly to all incoming requests. 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.

• header_read_timeout – Maximum time that NGINX Unit waits between two consecutive read() operations while reading the request body. When the timeout is exceeded, NGINX Unit responds with HTTP error 408 (Request Timeout). Default value: 30 seconds.
• body_read_timeout – Maximum time that NGINX Unit waits between two consecutive read() operations while reading the request body. When the timeout is exceeded, NGINX Unit responds with HTTP error 408 (Request Timeout). Default value: 30 seconds.
• send_timeout – Maximum time that NGINX Unit waits between two consecutive send() operations while transferring data to the client. When the timeout is exceeded, NGINX Unit closes the connection. Default value: 30 seconds.
• idle_timeout – Maximum wait time between HTTP requests in one keepalive connection. When the idle timeout is exceeded, NGINX Unit closes the keepalive connection. Default value: 180 seconds (3 minutes).

Note: Timeout values are defined as an integer in seconds.

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, NGINX 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 NGINX 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 8 MB (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 NGINX 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 NGINX Unit and the NGINX 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 NGINX Unit language packages.

    ---
    - hosts: localhost
      become: true
      roles:
        - role: nginxinc.nginx
      vars:
        nginx_enable: false
        unit_enable: true
        unit_modules:
          - 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.

Conclusion

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 NGINX Unit development is available in the source code repositories at https://hg.nginx.org/unit/file/tip/CHANGES, https://github.com/nginx/unit/blob/master/CHANGES, and on the NGINX Unit documentation site: https://unit.nginx.org/CHANGES.txt.

Watch our code repository on GitHub and join the discussions and development at https://github.com/nginx/unit.

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

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