隆重推出 NGINX Unit 1.2

Nick Shadrin of F5

Software Architect

2018-06-08

On June 7 we released NGINX Unit 1.2, the latest version of our dynamic multilingual application and web server, with support for many exciting features that enable its use in more sophisticated environments. This follows the general availability (GA) release of version 1.0 on April 12 and the release of version 1.1, with bug fixes and minor updates, just a couple weeks later.

NGINX Unit 1.2 includes these new features:

• All types of applications can now be dynamically configured with their own environment variables.
• Configuration options for PHP applications can be defined in the php.ini file or directly with the NGINX Unit API.
• Go executables can now be configured with command‑line arguments.

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

Let’s review the features in more detail.

Managing Environment Variables

When any application starts, it can get information about its environment from the operating system. As described in Wikipedia (as of June 8, 2018), environment variables “are part of the environment in which a process runs. For example, a running process can query the value of the TEMP environment variable to discover a suitable location to store temporary files, or the HOME or USERPROFILE variable to find the directory structure owned by the user running the process.”

In web applications, environment variables are often used to specify app parameters and credentials for access to services such as databases. (In this post we are not discussing the security of using environment variables for this purpose, and recommend doing your own research on the best ways to pass security credentials to applications.)

Starting in NGINX Unit 1.2, you can use the API to dynamically set environment variables for applications.

When you change the list of variables for an application, only the processes for that particular application are restarted, gracefully and without loss of any connections. Other applications running on the same instance of NGINX Unit are not affected.

Following are examples of how to add, change, and delete environment variables.

Minimal Configuration

This configuration defines the variable VAR1 for a Python app called myapp. We show only the minimal configuration:

{
    "listeners": {
        "*:8081": {
            "application": "myapp"
        }
    },

    "applications": {
        "myapp": {
            "type": "python",
            "path": "/srv/demo/var",
            "module": "wsgi",
            "environment": {
                "VAR1": "Hello world"
            }
        }
    }
}

We tested this configuration with the following minimal Python code, which returns the value of the VAR1 environment variable:

import os

def application(environ, start_response):
    output = os.environ['VAR1']
    start_response('200 OK', [('Content-type', 'text/html')])
    return [output.encode('utf-8')]

Defining an Environment Variable at Runtime

With a running instance of NGINX Unit, you can use the API to add a variable, either adding it to the existing configuration (as in this example) or by uploading an entire new configuration that includes it. This example defines the new environment variable Darkside:

# curl -X PUT -d '"We have cookies"' --unix-socket /run/control.unit.sock http://localhost/config/applications/myapp/environment/Darkside
{
    "success": "Reconfiguration done."
}

Displaying Environment Variables

To display all environment variables assigned to an application, access its environment object directly:

# curl --unix-socket /run/control.unit.sock http://localhost/config/applications/myapp/environment
{
    "VAR1": "Hello world",
    "Darkside": "We have cookies"
}

Or you can display just one variable by appending its name to the previous URL:

# curl --unix-socket ./control.unit.sock http://localhost/config/applications/myapp/environment/VAR1
"Hello world"

Deleting an Environment Variable

You can use the DELETE method to delete one variable at a time (as in this example) or the entire environment object:

# curl -X DELETE --unix-socket /run/control.unit.sock http://localhost/config/applications/myapp/environment/Darkside
{
    "success": "Reconfiguration done."
}

PHP Configuration and the php.ini File

When PHP starts up, it reads the system‑level php.ini file, which for an Ubuntu system running PHP 7 is located in the /etc/php/7.0/embed/ directory by default. By default, all PHP applications read the same configuration file.

There are many configuration options for PHP, which most of our users customize for their particular applications. Examples of these options include memory management, include paths, and temporary file locations. For more information, see the PHP documentation about the php.ini file and the core configuration options.

Starting in NGINX Unit 1.2, you can define the location of php.ini on a per‑application basis, and add specific configuration options directly with the API.

PHP reads php.ini only at startup, so when you change the file, you must restart the application workers for the relevant instances of the PHP application. When you use the NGINX Unit API to change configuration options, however, NGINX Unit reloads the PHP application workers automatically, with no dropped connections or effect on the running processes of other applications.

Full Configuration

This sample configuration defines /etc/my-configs/php.ini as the configuration file for the application called myphp:

{
    "listeners": {
        "*:8081": {
            "application": "myphp"
        }
    },

    "applications": {
        "myphp": {
            "type": "php",
            "root": "/srv/demo/phpini",
            "index": "index.php",
            "options": {
                "file": "/etc/my-configs/php.ini"
            }
        }
    }
}

Defining PHP Configuration Options at Runtime

You can use the NGINX Unit API to add new configuration options for use by a single application:

# curl -X PUT -d '{"expose_php": "0", "memory_limit": "256M"}' --unix-socket /run/control.unit.sock http://localhost/config/applications/myphp/options/admin
{
    "success": "Reconfiguration done."
}

Note: The value 0 (zero) for the expose_php option is enclosed in quotes because PHP configuration options are processed as strings, even when they represent numbers; in JSON, strings must be within quotes.

Displaying PHP Configuration Options

You can always display the currently defined configuration options:

# curl --unix-socket /run/control.unit.sock http://localhost/config/applications/myphp/options
{
    "file": "/etc/my-configs/php.ini",
    "admin": {
        "expose_php": "0",
        "memory_limit": "256M"
    }
}

Changing the Value of a PHP Configuration Option

You can change the value of one option at a time (as in the following example):

# curl -X PUT -d '"1"' --unix-socket /run/control.unit.sock http://localhost/config/applications/myphp/options/admin/expose_php
{
    "success": "Reconfiguration done."
}

You can also change multiple options at the same time by uploading the full options object.

Go Command-Line Arguments

Go executables are often designed to be configured with a set of command‑line arguments. You can define things like connectivity options, file locations, and database hosts.

Note: We recommend that you do not specify passwords or other sensitive information as command‑line options.

Starting in NGINX Unit 1.2, you can define Go command‑line arguments as a JSON array in the configuration.

For example, the command line might look like this for a Go app that is supposed to be executed with arguments to define a temporary file path:

# /srv/demo/go-apps/app --tmp-files /tmp/go-cache

When you start a Go app with NGINX Unit instead of a command, you need to specify such command‑line arguments in an arguments array in the configuration, as in this example:

{
    "listeners": {
        "*:8081": {
            "application": "mygo"
        }
    },

    "applications": {
        "mygo": {
            "type": "go",
            "executable": "/srv/demo/go-apps/app",
            "arguments": ["--tmp-files", "/tmp/go-cache"]
        }
    }
}

Conclusion

The new features in NGINX Unit 1.2 make it even easier to configure your applications. You can define all parameters dynamically, without any disruption to running services or loss of connectivity.

The full changelog for Unit development is available in the source code repositories (https://hg.nginx.org/unit/file/tip/CHANGES and https://github.com/nginx/unit/blob/master/CHANGES) and on the Unit documentation website (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 job board.

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