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:
settings
object in the configuration APIThese 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.
settings
ObjectOur 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:
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
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.
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.
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.
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.
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.
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!
"This blog post may reference products that are no longer available and/or no longer supported. For the most current information about available F5 NGINX products and solutions, explore our NGINX product family. NGINX is now part of F5. All previous NGINX.com links will redirect to similar NGINX content on F5.com."