NGINX Unit
v. 1.24.0

Configuration§

Quick Start§

To run an application on Unit, first set up an application object. Let’s store it in a file to PUT it into the config/applications section of Unit’s control API, available via the control socket at http://localhost/:

$ cat << EOF > config.json

    {
        "type": "php",
        "root": "/www/blogs/scripts"
    }
    EOF

# curl -X PUT --data-binary @config.json --unix-socket \
       /path/to/control.unit.sock http://localhost/config/applications/blogs

    {
        "success": "Reconfiguration done."
    }

Unit starts the application process. Next, reference the application object from a listener object, comprising an IP (or a wildcard to match any IPs) and a port number, in the config/listeners section of the API:

$ cat << EOF > config.json

    {
        "pass": "applications/blogs"
    }
    EOF

# curl -X PUT --data-binary @config.json --unix-socket \
       /path/to/control.unit.sock http://localhost/config/listeners/127.0.0.1:8300

    {
        "success": "Reconfiguration done."
    }

Unit accepts requests at the specified IP and port, passing them to the application process. Your app works!

Finally, check the resulting configuration:

# curl --unix-socket /path/to/control.unit.sock http://localhost/config/

    {
        "listeners": {
            "127.0.0.1:8300": {
                "pass": "applications/blogs"
            }
        },

        "applications": {
            "blogs": {
                "type": "php",
                "root": "/www/blogs/scripts/"
            }
        }
    }

You can upload the entire configuration at once or update it in portions. For details of configuration techniques, see below. For a full configuration sample, see here.

Configuration Management§

Unit’s configuration is JSON-based, accessed via the control socket, and entirely manageable over HTTP.

Note

Here, we use curl to query Unit’s control API, prefixing URIs with http://localhost as expected by this utility. You can use any tool capable of making HTTP requests; also, the hostname is irrelevant for Unit.

To address parts of the configuration, query the control socket over HTTP; URI path segments of your requests to the API must be names of its JSON object members or indexes of its array elements.

You can manipulate the API with the following HTTP methods:

MethodAction
GETReturns the entity at the request URI as a JSON value in the HTTP response body.
POSTUpdates the array at the request URI, appending the JSON value from the HTTP request body.
PUTReplaces the entity at the request URI and returns status message in the HTTP response body.
DELETEDeletes the entity at the request URI and returns status message in the HTTP response body.

Before a change, Unit evaluates the difference it causes in the entire configuration; if there’s none, nothing is done. For example, you can’t restart an updated app by uploading the same configuration it already has.

Note

While we’re working on handy app reload control, there’s a workaround to forcefully restart an app on Unit by updating an environment variable. First, check whether the app has an environment object:

# curl --unix-socket /path/to/control.unit.sock \
       http://localhost/config/applications/app/environment

      {
          "error": "Value doesn't exist."
      }

Here, it doesn’t, so you can safely add a new variable with a shell-interpolated value:

# curl -X PUT -d '{"APPGEN":"'$(date +"%s")'"}' --unix-socket \
       /path/to/control.unit.sock http://localhost/config/applications/app/environment

Otherwise, take care and target the individual variable to avoid overwriting the entire environment:

# curl -X PUT -d '"'$(date +"%s")'"' --unix-socket \
       /path/to/control.unit.sock http://localhost/config/applications/app/environment/APPGEN

To make Unit reload the app, repeat the PUT command, updating the APPGEN variable.

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:

# curl -X PUT -d '{ "pass": "applications/blogs" }' --unix-socket \
       /path/to/control.unit.sock http://localhost/config/listeners/127.0.0.1:8300

# curl -X PUT -d '"applications/blogs"' --unix-socket /path/to/control.unit.sock \
       http://localhost/config/listeners/127.0.0.1:8300/pass

However, mind that 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.

Examples

To minimize typos and effort, avoid embedding JSON payload in your commands; instead, consider storing your configuration snippets for review and reuse. Suppose you save your application object as wiki.json:

{
    "type": "python",
    "module": "wsgi",
    "user": "www-wiki",
    "group": "www-wiki",
    "path": "/www/wiki/"
}

Use it to set up an application called wiki-prod:

# curl -X PUT --data-binary @/path/to/wiki.json \
       --unix-socket /path/to/control.unit.sock http://localhost/config/applications/wiki-prod

Use it again to set up a development version of the same app called wiki-dev:

# curl -X PUT --data-binary @/path/to/wiki.json \
       --unix-socket /path/to/control.unit.sock http://localhost/config/applications/wiki-dev

Toggle the wiki-dev app to another source code directory:

# curl -X PUT -d '"/www/wiki-dev/"' \
       --unix-socket /path/to/control.unit.sock http://localhost/config/applications/wiki-dev/path

Next, boost the process count for the production app to warm it up a bit:

# curl -X PUT -d '5' \
       --unix-socket /path/to/control.unit.sock http://localhost/config/applications/wiki-prod/processes

Add a listener for the wiki-prod app to accept requests at all host IPs:

# curl -X PUT -d '{ "pass": "applications/wiki-prod" }' \
       --unix-socket /path/to/control.unit.sock 'http://localhost/config/listeners/*:8400'

Plug the wiki-dev app into the listener to test it:

# curl -X PUT -d '"applications/wiki-dev"' --unix-socket /path/to/control.unit.sock \
       'http://localhost/config/listeners/*:8400/pass'

Then rewire the listener, adding a URI-based route to the development version of the app:

$ cat << EOF > config.json

    [
        {
            "match": {
                "uri": "/dev/*"
            },

            "action": {
                "pass": "applications/wiki-dev"
            }
        }
    ]
    EOF

# curl -X PUT --data-binary @config.json --unix-socket \
       /path/to/control.unit.sock http://localhost/config/routes

# curl -X PUT -d '"routes"' --unix-socket \
       /path/to/control.unit.sock 'http://localhost/config/listeners/*:8400/pass'

Next, let’s change the wiki-dev’s URI prefix in the routes array using its index (0):

# curl -X PUT -d '"/development/*"' --unix-socket=/path/to/control.unit.sock \
       http://localhost/config/routes/0/match/uri

Let’s add a route to the prod app: POST always adds to the array end, so there’s no need for an index:

# curl -X POST -d '{"match": {"uri": "/production/*"}, \
       "action": {"pass": "applications/wiki-prod"}}'  \
       --unix-socket=/path/to/control.unit.sock        \
       http://localhost/config/routes/

Otherwise, use PUT with the array’s last index (0 in our sample) plus one to add the new item at the end:

# curl -X PUT -d '{"match": {"uri": "/production/*"}, \
       "action": {"pass": "applications/wiki-prod"}}' \
       --unix-socket=/path/to/control.unit.sock       \
       http://localhost/config/routes/1/

To get the complete config section:

# 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"
                }
            }
        ]
    }

To obtain the wiki-dev application object:

# 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/"
    }

You can save JSON returned by such requests as .json files for update or review:

# curl --unix-socket /path/to/control.unit.sock \
       http://localhost/config/ > config.json

To drop the listener on *:8400:

# curl -X DELETE --unix-socket /path/to/control.unit.sock \
       'http://localhost/config/listeners/*:8400'

Mind that you can’t delete objects that other objects rely on, such as a route still referenced by a listener:

# curl -X DELETE --unix-socket /var/run/unit/control.sock \
        http://localhost/config/routes

     {
         "error": "Invalid configuration.",
         "detail": "Request \"pass\" points to invalid location \"routes\"."
     }
Replicating Unit Configurations

Although Unit is fully dynamic, sometimes you just want to copy an existing setup without the need for subsequent meddling. Unit’s state directories are interchangeable, provided they are used by the same version of Unit that created them, so you can use a shortcut to replicate a Unit instance.

Warning

Unit’s state can change its structure between versions and shouldn’t be edited by external means.

On the machine where the reference Unit instance runs, find out where the state is stored:

$ unitd -h

      --state DIRECTORY    set state directory name
                           default: "/path/to/reference/unit/state"

Double-check that the state location isn’t overridden at startup:

$ ps ax | grep unitd
      ...
      unit: main v1.24.0 [unitd --state /runtime/path/to/reference/unit/state ... ]

Repeat these commands on the second machine to see where the target instance stores its state.

Stop both Unit instances, for example:

# systemctl stop unit

Note

Different stop and start commands may be needed if you use a non-official installation method.

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:

# systemctl restart unit

Note

If you run your Unit instances manually, --state can be used to set the state directory at startup.

After the restart, the target instance picks up the configuration you’ve copied to the state directory.

Listeners§

To start accepting requests, add a listener object in the config/listeners API section. The object’s name uniquely combines a host IP address and a port that Unit binds to; a wildcard matches any host IPs.

Note

On Linux-based systems, wildcard listeners can’t overlap with other listeners on the same port due to kernel-imposed limitations. For example, *:8080 conflicts with 127.0.0.1:8080; in partcular, this also means you can’t directly reconfigure a listener on *:8080 to use 127.0.0.1:8080 or vice versa without deleting it first.

Unit dispatches the requests it receives to destinations referenced by listeners. You can plug several listeners into one destination or use a single listener and hot-swap it between multiple destinations.

Available listener options:

OptionDescription
pass

Destination to which the listener passes incoming requests. Possible alternatives:

Note

The value is variable-interpolated; if it matches no configuration entities after interpolation, a 404 “Not Found” response is returned.

tlsSSL/TLS configuration object.

Here, a local listener accepts requests at port 8300 and passes them to the blogs app target identified by the uri variable. The wildcard listener on port 8400 relays requests at any host IPs to the main route:

{
    "127.0.0.1:8300": {
        "pass": "applications/blogs$uri"
    },

    "*:8400": {
        "pass": "routes/main"
    }
}

Also, pass values can be percent encoded. For example, you can escape slashes in entity names:

{
    "listeners": {
         "*:80": {
             "pass": "routes/slashes%2Fin%2Froute%2Fname"
         }
    },

    "routes": {
         "slashes/in/route/name": []
    }
}

SSL/TLS Configuration§

The tls object provides the following options:

OptionDescription
certificate (required)String or string array, refers to one or more certificate bundles you have uploaded earlier, enabling secure communication via the listener.
conf_commands

Object, defines SSL configuration commands to be set for the listener.

To provide this option, Unit must be built and run on a system with OpenSSL 1.0.2+:

$ openssl version

      OpenSSL 1.1.1d  10 Sep 2019

To use a certificate bundle you’ve uploaded earlier, name it in the certificate option of the tls object:

{
    "listeners": {
        "127.0.0.1:443": {
            "pass": "applications/wsgi-app",
            "tls": {
                "certificate": "bundle"
            }
        }
    }
}

To set custom OpenSSL configuration commands for a listener, use the conf_commands object in tls:

{
    "tls": {
        "certificate": "bundle",
        "conf_commands": {
            "ciphersuites": "TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256",
            "minprotocol": "TLSv1.3"
        }
    }
}
Configuring Multiple Bundles

Since version 1.23.0, Unit supports configuring Server Name Indication (SNI) on a listener by supplying an array of certificate bundle names for the certificate option value:

{
    "*:80": {
        "pass": "routes",
        "tls": {
            "certificate": [
                "bundleA",
                "bundleB",
                "bundleC"
            ]
        }
    }
}

If the connecting client sends a server name, Unit responds with the matching certificate bundle. If the name matches several bundles, exact matches trump wildcards; if ambiguity remains, the one listed first is used. If there’s no match or no server name was sent, Unit uses the first bundle on the list.

Routes§

The config/routes configuration entity defines internal request routing, receiving requests via listeners and filtering them through sets of conditions to be processed by apps, proxied to external servers or load-balanced between them, served with static content, answered with arbitrary status codes, or redirected.

In its simplest form, routes can be a single route array:

{
     "listeners": {
         "*:8300": {
             "pass": "routes"
         }
     },

     "routes": [ "..." ]
}

Another form is an object with one or more named route arrays as members:

{
     "listeners": {
         "*:8300": {
             "pass": "routes/main"
         }
     },

     "routes": {
         "main": [ "..." ],
         "route66": [ "..." ]
     }
}

Route Steps§

A route array contains step objects as elements; they accept the following options:

OptionDescription
action (required)Object that defines how matching requests are handled.
matchObject that defines the step’s conditions to be matched.

A request passed to a route traverses its steps sequentially:

  • If all match conditions in a step are met, the step’s action is performed.
  • If a step’s condition isn’t met, Unit proceeds to the next step of the route.
  • If no steps of the route match, a 404 “Not Found” response is returned.

Warning

If a step omits the match option, its action is performed automatically. Thus, use no more than one such step per route, always placing it last to avoid potential routing issues.

Ad-Hoc Examples

A basic one:

{
    "routes": [
        {
            "match": {
                "host": "example.com",
                "scheme": "https",
                "uri": "/php/*"
            },

            "action": {
                "pass": "applications/php_version"
            }
        },
        {
            "action": {
                "share": "/www/static_version/"
            }
        }
    ]
}

This route passes all requests to the /php/ subsection of the example.com website via HTTPS to the php_version app. All other requests are served with static content from the /www/static_version directory. If there’s no matching content. Unit returns a 404 response code.

A more elaborate example with chained routes and proxying:

{
    "routes": {
        "main": [
            {
                "match": {
                    "scheme": "http"
                },

                "action": {
                    "pass": "routes/http_site"
                }
            },
            {
                "match": {
                    "host": "blog.example.com"
                },

                "action": {
                    "pass": "applications/blog"
                }
            },
            {
                 "match": {
                     "uri": [
                         "*.css",
                         "*.jpg",
                         "*.js"
                     ]
                 },
                "action": {
                    "share": "/www/static/"
                }
            }
        ],

        "http_site": [
            {
                "match": {
                    "uri": "/v2_site/*"
                },

                "action": {
                    "pass": "applications/v2_site"
                }
            },
            {
                "action": {
                    "proxy": "http://127.0.0.1:9000"
                }
            }
        ]
    }
}

Here, a route called main is explicitly defined, so routes is an object instead of an array. The first step of the route passes all requests that arrive via HTTP to the http_site app. The second step passes all requests that target blog.example.com to the blog app. The final step serves requests for certain file types from the /www/static/ directory. If none of the steps matches, a 404 response code is returned.

Matching Conditions§

Conditions in a route step’s match object define patterns to be compared to the requests’ properties:

PropertyPatterns Are Matched AgainstCase‑Sensitive
argumentsParameter arguments supplied with the request’s target query. In argument names and values, plus signs (+) are replaced with spaces.Yes
cookiesCookies supplied with the request.Yes
destinationTarget IP address and optional port of the request.No
headersHeader fields supplied with the request.No
hostHost header field, converted to lower case and normalized by removing the port number and the trailing period (if any).No
methodMethod from the request line, converted to upper case.No
schemeURI scheme. Currently, only http and https are supported.No
sourceSource IP address and optional port of the request.No
uriRequest target path, normalized by removing the query part, resolving relative path references (“.” and “..”), and collapsing adjacent slashes.Yes
Percent Encoding In Arguments and URIs

Names and values in arguments and values in uri additionally support percent encoding. Thus, you can escape characters which have special meaning in routing (! is %21, * is %2A, % is %25), or even target individual bytes. For example, to select an entire class of diacritic characters such as Ö or Å by their starting byte 0xC3 in UTF-8:

{
    "match": {
        "arguments": {
            "word": "*%C3*"
        }
    },

    "action": {
        "pass": "..."
    }
}

This requires mentioning that actual arguments and URIs passed with requests are percent decoded: Unit interpolates all percent-encoded entities in these properties. Thus, the following configuration:

{
    "routes": [
        {
            "match": {
                "uri": "/static files/*"
            },

            "action": {
                "share": "/www/data/"
            }
        }
    ]
}

Matches this percent-encoded request:

$ curl http://127.0.0.1/static%20files/test.txt -v

      > GET /static%20files/test.txt HTTP/1.1
      ...
      < HTTP/1.1 200 OK
      ...

Match Resolution§

To be a match, the property must meet two requirements:

  • If there are patterns without negation (the ! prefix), at least one of them matches the property value.
  • No negated patterns match the property value.

Note

The scheme property accepts no patterns or arrays, but only two string values: http or https.

Here, the URI of the request must fit pattern3, but should not match pattern1 or pattern2.

{
    "match": {
        "uri": [
            "!pattern1",
            "!pattern2",
            "pattern3"
        ]
    },

    "action": {
        "pass": "..."
    }
}
Formal Explanation

This logic can be described with set operations. Suppose set U comprises all possible values of a property; set P comprises strings that match any patterns without negation; set N comprises strings that match any negation-based patterns. In this scheme, the matching set will be:

U ∩ P \ N if P ≠ ∅
U \ N if P = ∅

Additionally, special matching logic is used for arguments, cookies, and headers. Each of these can be a single object that lists custom-named properties and their patterns or an array of such objects.

To match a single object, the request must match all properties named in the object. To match an object array, it’s enough to match any single one of its item objects. The following condition will match only if the request arguments include both arg1 and arg2 and they match their patterns:

{
    "match": {
        "arguments": {
            "arg1": "pattern",
            "arg2": "pattern"
        }
    },

    "action": {
        "pass": "..."
    }
}

With an object array, the condition will match if the request’s arguments include either arg1 or arg2 (or maybe both) that matches the respective pattern:

{
    "match": {
        "arguments": [
            {
                "arg1": "pattern"
            },

            {
                "arg2": "pattern"
            }
        ]
    },

    "action": {
        "pass": "..."
    }
}

The following example combines all matching types. Here, host, method, uri, arg1 and arg2, either cookie1 or cookie2, and either header1 or header2 and header3 must be matched for the action to be taken (host & method & uri & arg1 & arg2 & (cookie1 | cookie2) & (header1 | (header2 & header3))):

{
    "match": {
        "host": "pattern",
        "method": "!pattern",
        "uri": [
            "pattern",
            "!pattern"
        ],

        "arguments": {
            "arg1": "pattern",
            "arg2": "!pattern"
        },

        "cookies": [
            {
                "cookie1": "pattern",
            },

            {
                "cookie2": "pattern",
            }
        ],

        "headers": [
            {
                "header1": "pattern",
            },

            {
                "header2": "pattern",
                "header3": "pattern"
            }
        ]
    },

    "action": {
        "pass": "..."
    }
}
Object Pattern Examples
{
    "match": {
        "arguments": {
            "mode": "strict",
            "access": "!full"
        }
    },

    "action": {
        "pass": "..."
    }
}

This requires mode=strict and any access argument other than access=full in the URI query.

{
    "match": {
        "headers": [
            {
                "Accept-Encoding": "*gzip*",
                "User-Agent": "Mozilla/5.0*"
            },

            {
                "User-Agent": "curl*"
            }
        ]
    },

    "action": {
        "pass": "..."
    }
}

This matches requests that either use gzip and identify as Mozilla/5.0 or list curl as the user agent.

Pattern Syntax§

Individual patterns can be address-based (source and destination) or string-based (other properties).

String-based patterns must match the property to a character; wildcards or regexes modify this behavior:

  • A wildcard pattern may contain any combination of wildcards (*), each standing for an arbitrary number of characters: How*s*that*to*you.
  • A regex pattern starts with a tilde (~): ~^\\d+\\.\\d+\\.\\d+\\.\\d+ (escaping backslashes is a JSON requirement). Regexes are PCRE-flavored.
String Pattern Examples
{
    "match": {
        "uri": "~^/data/www/.*\\.php(/.*)?$"
    },

    "action": {
        "pass": "..."
    }
}

A regular expression that matches any .php files within the /data/www/ directory and its subdirectories. Note the backslashes; escaping is a JSON-specific requirement.

{
    "match": {
        "host": "*.example.com"
    },

    "action": {
        "pass": "..."
    }
}

Only subdomains of example.com will match.

{
    "match": {
        "uri": "/admin/*/*.php"
    },

    "action": {
        "pass": "..."
    }
}

Only requests for .php files located in /admin/’s subdirectories will match.

{
    "match": {
        "host": [
            "eu-*.example.com",
            "!eu-5.example.com"
        ]
    },

    "action": {
        "pass": "..."
    }
}

Here, any eu- subdomains of example.com will match except eu-5.example.com.

{
    "match": {
        "method": [
            "!HEAD",
            "!GET"
        ]
    },

    "action": {
        "pass": "..."
    }
}

Any methods will match except HEAD and GET.

You can also combine certain special characters in a pattern:

{
    "match": {
        "uri": "!*/api/*"
    },

    "action": {
        "pass": "..."
    }
}

Here, any URIs will match except the ones containing /api/.

{
    "match": {
        "uri": [
            "/articles/*",
            "!~/articles/\\d{4}-\\d{2}-\\d{2}"
        ]
    },

    "action": {
        "pass": "..."
    }
}

Here, URIs of any articles that don’t look like YYYY-MM-DD dates will match. Again, note the backslashes; this is a JSON requirement.

Address-based patterns define individual IPv4 (dot-decimal or CIDR) or IPv6 (hexadecimal or CIDR) addresses that must exactly match the property value; wildcards and ranges modify this behavior:

  • Wildcards (*) can only be used to match arbitrary IPs (*:<port>).
  • Ranges (-) can used with both IPs (in respective notation) and ports (<start_port>-<end_port>).
Address Pattern Examples
{
    "match": {
        "source": [
            "10.0.0.0-10.255.255.255",
            "10.0.0.0-11.255.255.255:8000",
            "8.0.0.0-11.255.255.255:8080-8090",
            "*:80"
        ],

        "destination": [
            "10.0.0.0/8",
            "10.0.0.0/7:8000",
            "10.0.0.0/6:8080-8090",
            "*:80"
        ]
    },

    "action": {
        "pass": "..."
    }
}

This uses IPv4-based matching with wildcards and ranges.

{
    "match": {
        "source": [
             "2001::-200f:ffff:ffff:ffff:ffff:ffff:ffff:ffff",
             "[fe08::-feff::]:8000",
             "[fff0::-fff0::10]:8080-8090",
             "*:80"
        ],

        "destination": [
             "2001::/16",
             "[0ff::/64]:8000",
             "[fff0:abcd:ffff:ffff:ffff::/128]:8080-8090",
             "*:80"
        ]
    },

    "action": {
        "pass": "..."
    }
}

This uses IPv6-based matching with wildcards and ranges.

{
    "match": {
        "destination": [
            "127.0.0.1",
            "192.168.0.1",
            "::1",
            "2002:c0a8:0001::c0a8:0001"
        ]
    },

    "action": {
        "pass": "..."
    }
}

This matches any of the listed IPv4 or IPv6 addresses.

{
    "match": {
        "source": [
            "10.0.0.0-10.0.0.10",
            "!10.0.0.9"
        ]
    },

    "action": {
        "pass": "..."
    }
}

Here, any IPs from the range will match, except for 10.0.0.9.

{
    "match": {
        "source": [
            "*:80",
            "*:443",
            "*:8000-8080"
        ]
    },

    "action": {
        "pass": "..."
    }
}

This matches any IPs but limits the acceptable ports.

Handling Actions§

If a request matches all conditions of a route step or the step itself omits the match object, Unit handles the request using the respective action. The mutually exclusive action types are:

OptionDescriptionDetails
passDestination for the request, identical to a listener’s pass option.Listeners
proxySocket address of an HTTP server where the request is proxied.Proxying
returnHTTP status code with a context-dependent redirect location.Instant Responses, Redirects
shareDirectory location that serves the request with static content.Static Files

An example:

{
    "routes": [
        {
            "match": {
                "uri": "/pass/*"
            },

            "action": {
                "pass": "applications/app"
            }
        },
        {
            "match": {
                "uri": "~\\.jpe?g$"
            },

            "action": {
                "share": "/var/www/static/",
                "fallback": {
                    "share": "/var/www/static/assets",
                    "fallback": {
                         "pass": "upstreams/cdn"
                    }
                }
            }
        },
        {
            "match": {
                "uri": "/proxy/*"
            },

            "action": {
                "proxy": "http://192.168.0.100:80"
            }
        },
        {
            "match": {
                "uri": "/return/*"
            },

            "action": {
                "return": 301,
                "location": "https://www.example.com"
            }
        }
    ]
}

Variables§

While configuring Unit, you can use built-in variables that are replaced by dynamic values in runtime. This enables flexible request processing, making the configuration more compact and straightforward.

Note

Currently, the only place where variables are recognized is the pass option in listeners and actions. This means you can use them to guide requests between sets of routes, applications, targets, or upstreams.

Available variables:

VariableDescription
hostHost header field in lowercase, without the port number and the trailing period (if any).
methodMethod from the request line.
uriRequest target path without the query part, normalized by resolving relative path references (“.” and “..”) and collapsing adjacent slashes. The value is percent decoded: Unit interpolates all percent-encoded entities in the request target path.

To reference a variable, prefix its name with the dollar sign character ($), optionally enclosing the name in curly brackets ({}) to separate it from adjacent text or enhance visibility. Variable names can contain letters and underscores (_), so use the brackets if the variable is immediately followed by these characters:

{
    "listeners": {
        "*:80": {
            "pass": "routes/${method}_route"
        }
    },

    "routes": {
        "GET_route": [
            {
                "action": {
                    "return": 201
                }
            }
        ],

        "PUT_route": [
            {
                "action": {
                    "return": 202
                }
            }
        ],

        "POST_route": [
            {
                "action": {
                    "return": 203
                }
            }
        ]
    }
}

At runtime, variables are replaced by dynamically computed values (at your risk!). For example, the listener above targets an entire set of routes, picking individual ones by HTTP verbs that the incoming requests use:

$ curl -i -X GET http://localhost

    HTTP/1.1 201 Created

$ curl -i -X PUT http://localhost

    HTTP/1.1 202 Accepted

$ curl -i -X POST http://localhost

    HTTP/1.1 203 Non-Authoritative Information

$ curl -i --head http://localhost  # Bumpy ride ahead, no route defined

    HTTP/1.1 404 Not Found

Another obvious usage is employing the URI to choose between applications:

{
    "listeners": {
        "*:80": {
            "pass": "applications$uri"
        }
    },

    "applications": {
        "blog": {
            "root": "/path/to/blog_app/",
            "script": "index.php"
        },

        "sandbox": {
            "type": "php",
            "root": "/path/to/sandbox_app/",
            "script": "index.php"
        }
    }
}

This way, we can route requests to applications by request target URIs. A different approach can route requests between applications by the Host header field received from the client:

{
    "listeners": {
        "*:80": {
            "pass": "applications/$host"
        }
    },

    "applications": {
        "localhost": {
            "root": "/path/to/admin_section/",
            "script": "index.php"
        },

        "www.example.com": {
            "type": "php",
            "root": "/path/to/public_app/",
            "script": "index.php"
        }
    }
}

You can combine variables as you see fit, repeating them or placing them in arbitrary order. This configuration picks application targets by their names and request methods:

{
    "listeners": {
        "*:80": {
            "pass": "applications/app${uri}_${method}"
        }
    }
}

Instant Responses, Redirects§

You can use route step actions to instantly respond to certain conditions with arbitrary HTTP status codes:

{
    "match": {
        "uri": "/admin_console/*"
    },

    "action": {
        "return": 403
    }
}

The return action provides the following options:

return (required)Integer (000-999), defines the HTTP response status code to be returned.
locationURI, required if the return value implies redirection.

It is recommended to use the codes according to their semantics; if you use custom codes, make sure that user agents can understand them.

If you specify a redirect code (3xx), supply the destination using the location option alongside return:

{
    "action": {
        "return": 301,
        "location": "https://www.example.com"
    }
}

Static Files§

Unit is capable of acting as a standalone web server, serving requests for static assets from directories you configure; to use the feature, supply the directory path in the share option of a route step action:

{
    "listeners": {
        "127.0.0.1:8300": {
            "pass": "routes"
        }
     },

    "routes": [
        {
            "action": {
                "share": "/www/data/static/"
            }
        }
    ]
}

The share action provides the following options:

share (required)Directory pathname from where the static files are served.
fallbackAction-like object, used if the requested file can’t be served.
typesArray of MIME type patterns, used to filter the shared files.
chrootDirectory pathname that becomes the share’s new root.
follow_symlinks, traverse_mounts

Booleans, enable or disable symbolic link and mount point resolution respectively; if chroot is set, their effect starts from the new root.

The default for both options is true (resolve links and mounts).

Note

To serve the assets, Unit’s router process must be able to access them; thus, the account this process runs as must have proper permissions assigned. When Unit is installed from the official packages, the process runs as unit:unit; for details of other installation methods, see Installation.

Suppose the /www/data/static/ directory has the following structure:

/www/data/static/
├── stylesheet.css
├── html
│   └──index.html
└── js files
    └──page.js

In the above configuration, you can request specific files by these URIs:

$ curl http://localhost:8300/html/index.html
$ curl http://localhost:8300/stylesheet.css
$ curl http://localhost:8300/js%20files/page.js

If the request URI specifies only the directory name, Unit attempts to serve an index.html file from this directory but doesn’t apply MIME filtering:

$ curl -vL http://localhost:8300/html/

 ...
 < HTTP/1.1 200 OK
 < Last-Modified: Fri, 20 Sep 2019 04:14:43 GMT
 < ETag: "5d66459d-d"
 < Content-Type: text/html
 < Server: Unit/1.24.0
 ...

Note

Unit’s ETag response header fields use the MTIME-FILESIZE format, where MTIME stands for file modification timestamp and FILESIZE stands for file size in bytes, both in hexadecimal.

MIME Filtering§

To filter the files a share serves by their MIME types, define a types array of string patterns. They work like route patterns but are matched to the MIME type of each file; the request is served only if it’s a match:

{
    "share": "/www/data/static/",
    "types": [
        "!text/javascript",
        "!text/css",
        "text/*",
        "~video/3gpp2?"
    ]
}

This sample configuration blocks JS and CSS files with negation but allows all other text-based MIME types with a wildcard pattern. Additionally, the .3gpp and .3gpp2 file types are allowed by a regex pattern.

If the MIME type of a requested file isn’t recognized, it is considered empty (""). Thus, the "!" pattern (“deny empty strings”) can be used to restrict all file types unknown to Unit:

{
    "share": "/www/data/known-types-only/",
    "types": [
        "!"
    ]
}

Path Restrictions§

Note

To provide these options, Unit must be built and run on a system with Linux kernel version 5.6+.

The chroot option effectively confines path resolution of files served from a share to a new root directory. One notable effect of enabling chroot is that symbolic links to absolute pathnames are treated as relative to the new root; thus, a symlink to /log/app.log in this example is resolved as /www/data/log/app.log:

{
    "action": {
        "share": "/www/data/static/",
        "chroot": "/www/data/"
    }
}

The share path stays as is and won’t be treated as relative; only the portions that occur after the new root (if any) are affected by the new behavior. Moreover, any requests for files outside the new root will fail:

{
    "action": {
        "share": "/www/",
        "chroot": "/www/data/"
    }
}

In this configuration, a request for /index.xml will result in status code 403 because it will be resolved as /www/index.xml, which is outside the new root.

The follow_symlinks and traverse_mounts options disable resolution of symbolic links and traversal of mount points when set to false (both default to true):

{
    "action": {
        "share": "/www/data/static/",
        "follow_symlinks": false,
        "traverse_mounts": false
    }
}

Here, any request that involves a symlink or a mount point inside /www/data/static/ will fail; also, if a portion of the share path is a symlink or a mount point, this configuration will be accepted but won’t work.

With chroot set, follow_symlinks and traverse_mounts only affect portions of the path after the new root:

{
    "action": {
        "share": "/www/data/static/",
        "chroot": "/www/data/",
        "follow_symlinks": false,
        "traverse_mounts": false
    }
}

Here, www/ and data/ can be symlinks or mount points, but any symlinks and mount points beyond them, including the static/ portion, won’t be resolved.

Details

Suppose you want to serve files from a share that itself includes a symlink (say, data/ in our example) but disable any symlinks inside the share. Initial configuration:

{
    "action": {
        "share": "/www/data/static/",
        "chroot": "/www/data/"
    }
}

Let’s create a symlink to /www/data/static/index.html:

$ cat > /www/data/static/index.html <<EOF

      > index.html
      > EOF

$ ln -s index.html /www/data/static/symlink

If symlink resolution is enabled (with or without chroot), a request that targets the symlink works:

$ curl http://localhost/index.html

      index.html

$ curl http://localhost/symlink

      index.html

Let’s set follow_symlinks to false:

{
    "action": {
        "share": "/www/data/static/",
        "chroot": "/www/data/",
        "follow_symlinks": false
    }
}

Now the symlink request fails, which is the desired effect:

$ curl http://localhost/index.html

      index.html

$ curl http://localhost/symlink

      <!DOCTYPE html><title>Error 403</title><p>Error 403.

Lastly, what difference does chroot make? Let’s remove it:

{
    "action": {
        "share": "/www/data/static/",
        "follow_symlinks": false
    }
}

This request fails because "follow_symlinks": false affects the entire share, and data/ is a symlink:

$ curl http://localhost/index.html

      <!DOCTYPE html><title>Error 403</title><p>Error 403.

Fallback Action§

Finally, within an action, you can supply a fallback option beside a share. It specifies the action to be taken if the requested file can’t be served from the share path:

{
    "share": "/www/data/static/",
    "fallback": {
        "pass": "applications/php"
    }
}

Serving a file can be impossible for different reasons, such as:

  • The request’s HTTP method isn’t GET or HEAD.
  • The file’s MIME type doesn’t match the types array.
  • The file isn’t found at the share path.
  • The router process has insufficient permissions to access the file or an underlying directory.

In the example above, an attempt to serve the requested file from the /www/data/static/ directory is made first. Only if the file can’t be served, the request is passed to the php application.

If the fallback itself is a share, it can also contain a nested fallback:

{
    "share": "/www/data/static/",
    "fallback": {
        "share": "/www/data/cache/",
        "fallback": {
            "proxy": "http://127.0.0.1:9000"
        }
    }
}

First, this configuration tries to serve the request from the /www/data/static/ directory; on failure, it queries the /www/data/cache/ path. Only if both attempts fail, the request is proxied to an external server.

Examples

One common use case that this feature enables is the separation of requests for static and dynamic content into independent routes. The following example relays all requests that target .php files to an application and uses a catch-all static share with a fallback:

{
    "routes": [
        {
            "match": {
                "uri": "*.php"
            },

            "action": {
                "pass": "applications/php-app"
            }
        },
        {
            "action": {
                "share": "/www/php-app/assets/files/",
                "fallback": {
                    "proxy": "http://127.0.0.1:9000"
                }
            }
        }

    ],

    "applications": {
        "php-app": {
            "type": "php",
            "root": "/www/php-app/scripts/"
        }
    }
}

You can reverse this scheme for apps that avoid filenames in dynamic URIs, listing all types of static content to be served from a share in a match condition and adding an unconditional application path:

{
    "routes": [
        {
            "match": {
                "uri": [
                    "*.css",
                    "*.ico",
                    "*.jpg",
                    "*.js",
                    "*.png",
                    "*.xml"
                ]
            },

            "action": {
                "share": "/www/php-app/assets/files/",
                "fallback": {
                    "proxy": "http://127.0.0.1:9000"
                }
            }
        },
        {
            "action": {
                "pass": "applications/php-app"
            }
        }

    ],

    "applications": {
        "php-app": {
            "type": "php",
            "root": "/www/php-app/scripts/"
        }
    }
}

If image files should be served locally and other proxied, use the types array in the first route step:

{
    "match": {
        "uri": [
            "*.css",
            "*.ico",
            "*.jpg",
            "*.js",
            "*.png",
            "*.xml"
        ]
    },

    "action": {
        "share": "/www/php-app/assets/files/",
        "types": [
            "image/*"
        ],
        "fallback": {
            "proxy": "http://127.0.0.1:9000"
        }
    }
}

Another way to combine share, types, and fallback is exemplified by the following compact pattern:

{
    "share": "/www/php-app/assets/files/",
    "types": [
        "!application/x-httpd-php"
    ],
    "fallback": {
        "pass": "applications/php-app"
    }
}

It forwards explicit requests for PHP files to the app while serving all other types of files from the share; note that a match object isn’t needed here to achieve this effect.

Proxying§

Unit’s routes support HTTP proxying to socket addresses using the proxy option of a route step action:

{
    "routes": [
        {
            "match": {
                "uri": "/ipv4/*"
            },

            "action": {
                "proxy": "http://127.0.0.1:8080"
            }
        },
        {
            "match": {
                "uri": "/ipv6/*"
            },

            "action": {
                "proxy": "http://[::1]:8080"
            }
        },
        {
            "match": {
                "uri": "/unix/*"
            },

            "action": {
                "proxy": "http://unix:/path/to/unix.sock"
            }
        }
    ]
}

As the example above suggests, you can use Unix, IPv4, and IPv6 socket addresses for proxy destinations.

Note

The HTTPS scheme is not supported yet.

Load Balancing§

Besides proxying requests to individual servers, Unit can also relay incoming requests to upstreams. An upstream is a group of servers that comprise a single logical entity and may be used as a pass destination for incoming requests in a listener or a route.

Upstreams are defined in the eponymous config/upstreams section of the API:

{
    "listeners": {
        "*:80": {
            "pass": "upstreams/rr-lb"
        }
    },

    "upstreams": {
        "rr-lb": {
            "servers": {
                "192.168.0.100:8080": { },
                "192.168.0.101:8080": {
                    "weight": 0.5
                }
            }
        }
    }
}

An upstream must define a servers object that lists socket addresses as server object names. Unit dispatches requests between the upstream’s servers in a round-robin fashion, acting as a load balancer. Each server object can set a numeric weight to adjust the share of requests it receives via the upstream. In the above example, 192.168.0.100:8080 receives twice as many requests as 192.168.0.101:8080.

Weights can be specified as integers or fractions in decimal or scientific notation:

{
    "servers": {
        "192.168.0.100:8080": {
            "weight": 1e1
        },
        "192.168.0.101:8080": {
            "weight": 10.0
        },
        "192.168.0.102:8080": {
            "weight": 10
        }
    }
}

The maximum weight is 1000000, the minimum is 0 (such servers receive no requests), the default is 1.

Applications§

Each app that Unit runs is defined as an object in the config/applications section of the control API; it lists the app’s language and settings, its runtime limits, process model, and various language-specific options.

Note

Our official language support packages include end-to-end examples of application configuration, available for your reference at /usr/share/doc/<module name>/examples/ after package installation.

Here, Unit runs 20 processes of a PHP app called blogs, stored in the /www/blogs/scripts/ directory:

{
    "blogs": {
        "type": "php",
        "processes": 20,
        "root": "/www/blogs/scripts/"
    }
}

App objects have a number of options shared between all application languages:

OptionDescription
type (required)

Application type: external (Go and Node.js), java, perl, php, python, or ruby.

Except with external, you can detail the runtime version: "type": "python 3", "type": "python 3.4", or even "type": "python 3.4.9rc1". Unit searches its modules and uses the latest matching one, reporting an error if none match.

For example, if you have only one PHP module, 7.1.9, it matches "php", "php 7", "php 7.1", and "php 7.1.9". If you have modules for versions 7.0.2 and 7.0.23, set "type": "php 7.0.2" to specify the former; otherwise, PHP 7.0.23 will be used.

limitsObject that accepts two integer options, timeout and requests. Their values govern the life cycle of an application process. For details, see here.
processes

Integer or object. Integer sets a static number of app processes; object options max, spare, and idle_timeout enable dynamic management. For details, see here.

The default value is 1.

working_directoryThe app’s working directory. If not set, the Unit daemon’s working directory is used.
userUsername that runs the app process. If not set, the username configured at build time or at startup to run Unit’s non-privileged processes is used.
groupGroup name that runs the app process. If not set, the user’s primary group is used.
environmentEnvironment variables to be passed to the application.

Also, you need to set type-specific options to run the app. This Python app uses path and module:

{
    "type": "python 3.6",
    "processes": 16,
    "working_directory": "/www/python-apps",
    "path": "blog",
    "module": "blog.wsgi",
    "user": "blog",
    "group": "blog",
    "environment": {
        "DJANGO_SETTINGS_MODULE": "blog.settings.prod",
        "DB_ENGINE": "django.db.backends.postgresql",
        "DB_NAME": "blog",
        "DB_HOST": "127.0.0.1",
        "DB_PORT": "5432"
    }
}

Process Management§

Unit supports three per-app options that control the app’s processes: isolation, limits, and processes.

Process Isolation§

You can use namespace and file system isolation for your apps if Unit’s underlying OS supports them:

$ ls /proc/self/ns/

    cgroup  ipc  mnt  net  pid  ...  user  uts

The isolation application option has the following members:

OptionDescription
namespaces

Object that configures namespace isolation scheme for the application.

Available options (system-dependent; check your OS manual for guidance):

cgroupCreates a new cgroup namespace for the app.
credentialCreates a new user namespace for the app.
mountCreates a new mount namespace for the app.
networkCreates a new network namespace for the app.
pidCreates a new PID namespace for the app.
unameCreates a new UTS namespace for the app.

All options listed above are Boolean; to isolate the app, set the corresponding namespace option to true; to disable isolation, set the option to false (default).

uidmap

Array of ID mapping objects; each array item must define the following:

containerInteger that starts the user ID mapping range in the app’s namespace.
hostInteger that starts the user ID mapping range in the OS namespace.
sizeInteger size of the ID range in both namespaces.
gidmapSame as uidmap, but configures group IDs instead of user IDs.
rootfsPathname of the directory to be used as the new file system root for the app.
automount

Object that controls mount behavior if rootfs is enabled. By default, Unit automatically mounts the language runtime dependencies, a procfs at /proc/, and a tmpfs at /tmp/, but you can disable any of these default mounts:

{
    "isolation": {
        "automount": {
            "language_deps": false,
            "procfs": false,
            "tmpfs": false
        }
    }
}

A sample isolation object that enables all namespaces and sets mappings for user and group IDs:

{
    "namespaces": {
        "cgroup": true,
        "credential": true,
        "mount": true,
        "network": true,
        "pid": true,
        "uname": true
    },

    "uidmap": [
        {
            "host": 1000,
            "container": 0,
            "size": 1000
        }
    ],

    "gidmap": [
        {
            "host": 1000,
            "container": 0,
            "size": 1000
        }
    ]
}
Using Uidmap And Gidmap

The uidmap and gidmap options are available only if the underlying OS supports user namespaces.

If uidmap is omitted but credential isolation is enabled, the effective UID (EUID) of the application process in the host namespace is mapped to the same UID in the container namespace; the same applies to gidmap and GID, respectively. This means that the configuration below:

{
    "user": "some_user",
    "namespaces": {
        "credential": true
    }
}

Is equivalent to the following (assuming some_user’s EUID and EGID are both equal to 1000):

{
    "user": "some_user",
    "namespaces": {
        "credential": true
    },
    "uidmap": [
        {
            "host": "1000",
            "container": "1000",
            "size": 1
        }
    ],

    "gidmap": [
        {
            "host": "1000",
            "container": "1000",
            "size": 1
        }
    ]
}

The rootfs option confines the app to the directory you provide, making it the new file system root. To use it, your app should have the corresponding privilege (effectively, run as root in most cases).

The root directory is changed before the language module starts the app, so any path options for the app should be relative to the new root. Note the path and home settings:

{
    "type": "python 2.7",
    "path": "/",
    "home": "/venv/",
    "module": "wsgi",
    "isolation": {
        "rootfs": "/var/app/sandbox/"
    }
}

Unit mounts language-specific files and directories to the new root so the app stays operational:

LanguageLanguage-Specific Mounts
Java
  • JVM’s libc.so directory
  • Java module’s home directory
PythonPython’s sys.path directories
Ruby
  • Ruby’s header, interpreter, and library directories: rubyarchhdrdir, rubyhdrdir, rubylibdir, rubylibprefix, sitedir, and topdir
  • Ruby’s gem installation directory (gem env gemdir)
  • Ruby’s entire gem path list (gem env gempath)

Request Limits§

The limits object controls request handling by the app process and has two integer options:

OptionDescription
timeoutRequest timeout in seconds. If an app process exceeds this limit while handling a request, Unit alerts it to cancel the request and returns an HTTP error to the client.
requestsMaximum number of requests Unit allows an app process to serve. If the limit is reached, the process is restarted; this helps to mitigate possible memory leaks or other cumulative issues.

Example:

{
    "type": "python",
    "working_directory": "/www/python-apps",
    "module": "blog.wsgi",
    "limits": {
        "timeout": 10,
        "requests": 1000
    }
}

Process Management§

The processes option offers a choice between static and dynamic process management. If you set it to an integer, Unit immediately launches the given number of app processes and keeps them without scaling.

To enable a dynamic prefork model for your app, supply a processes object with the following options:

OptionDescription
max

Maximum number of application processes that Unit will maintain (busy and idle).

The default value is 1.

spareMinimum number of idle processes that Unit tries to reserve for an app. When the app is started, spare idle processes are launched; Unit assigns incoming requests to existing idle processes, forking new idles to maintain the spare level if max allows. As processes complete requests and turn idle, Unit terminates extra ones after idle_timeout.
idle_timeoutTime in seconds that Unit waits before terminating an idle process which exceeds spare.

If processes is omitted entirely, Unit creates 1 static process. If an empty object is provided: "processes": {}, dynamic behavior with default option values is assumed.

Here, Unit allows 10 processes maximum, keeps 5 idles, and terminates extra idles after 20 seconds:

{
    "max": 10,
    "spare": 5,
    "idle_timeout": 20
}

Go§

To run your Go apps on Unit, you need to configure them and modify their source code as suggested below. Let’s start with the app configuration; besides common options, you have:

OptionDescription
executable (required)Pathname of the application, absolute or relative to working_directory.
argumentsCommand line arguments to be passed to the application. The example below is equivalent to /www/chat/bin/chat_app --tmp-files /tmp/go-cache.

Example:

{
    "type": "external",
    "working_directory": "/www/chat",
    "executable": "bin/chat_app",
    "user": "www-go",
    "group": "www-go",
    "arguments": ["--tmp-files", "/tmp/go-cache"]
}

Before applying the configuration, update the application source code:

In the import section, reference the unit.nginx.org/go package that you installed or built earlier:

import (
    ...
    "unit.nginx.org/go"
    ...
)

Note

The package is required only to build the app; there’s no need to install it in the target environment.

In the main() function, replace the http.ListenAndServe call with unit.ListenAndServe:

func main() {
    ...
    http.HandleFunc("/", handler)
    ...
    //http.ListenAndServe(":8080", nil)
    unit.ListenAndServe(":8080", nil)
    ...
}

The resulting application works as follows:

  • When you run it standalone, the unit.ListenAndServe call falls back to http functionality.
  • When Unit runs it, unit.ListenAndServe communicates with Unit’s router process directly, ignoring the address supplied as its first argument and relying on the listener’s settings instead.

If you update Unit later, update the Go package as well according to your installation method. You’ll also need to rebuild your app with the updated package.

Note

For Go-based examples, see our Grafana howto or a basic sample.

Java§

First, make sure to install Unit along with the Java language module.

Besides common options, you have the following:

OptionDescription
webapp (required)Pathname of the application’s packaged or unpackaged .war file.
classpathArray of paths to your app’s required libraries (may list directories or .jar files).
optionsArray of strings defining JVM runtime options.
threads

Integer that sets the number of worker threads per app process. When started, each app process creates a corresponding number of threads to handle requests.

The default value is 1.

thread_stack_size

Integer that defines the stack size of a worker thread (in bytes, multiple of memory page size; the minimum value is usually architecture specific).

The default value is system dependent and can be set with ulimit -s <SIZE_KB>.

Example:

{
    "type": "java",
    "classpath": ["/www/qwk2mart/lib/qwk2mart-2.0.0.jar"],
    "options": ["-Dlog_path=/var/log/qwk2mart.log"],
    "webapp": "/www/qwk2mart/qwk2mart.war"
}

Note

For Java-based examples, see our Jira, OpenGrok, and Spring Boot howtos or a basic sample.

Node.js§

First, you need to have the unit-http module installed. If it’s global, symlink it in your project directory:

# npm link unit-http

Do the same if you move a Unit-hosted app to a new system where unit-http is installed globally. Also, if you update Unit later, update the Node.js module as well according to your installation method.

Next, to run your Node.js apps on Unit, you need to configure them. Besides common options, you have:

OptionDescription
executable (required)

Pathname of the application, absolute or relative to working_directory.

Supply your .js pathname here and start the file itself with a proper shebang:

#!/usr/bin/env node

Note

Make sure to chmod +x the file you list here so Unit can start it.

argumentsCommand line arguments to be passed to the application. The example below is equivalent to /www/apps/node-app/app.js --tmp-files /tmp/node-cache.

Example:

{
    "type": "external",
    "working_directory": "/www/app/node-app/",
    "executable": "app.js",
    "user": "www-node",
    "group": "www-node",
    "arguments": [
        "--tmp-files",
        "/tmp/node-cache"
    ]
}

You can run Node.js apps without altering their code, using a loader module we provide with unit-http. Apply the following app configuration, depending on your version of Node.js:

{
    "type": "external",
    "executable": "/usr/bin/env",
    "arguments": [
        "node",
        "--loader",
        "unit-http/loader.mjs",
        "--require",
        "unit-http/loader",
        "app.js"
    ]
}

{
    "type": "external",
    "executable": "/usr/bin/env",
    "arguments": [
        "node",
        "--require",
        "unit-http/loader",
        "app.js"
    ]
}

The loader overrides the http and websocket modules with their Unit-aware versions and starts the app.

You can also run your Node.js apps without the loader by updating the application source code. For that, use unit-http instead of http in your code:

var http = require('unit-http');

To use the WebSocket protocol, your app only needs to replace the default websocket:

var webSocketServer = require('unit-http/websocket').server;

Note

For Node.js-based examples, see our Express and Docker howtos or a basic sample.

Perl§

First, make sure to install Unit along with the Perl language module.

Besides common options, you have the following:

OptionDescription
script (required)PSGI script path.
threads

Integer that sets the number of worker threads per app process. When started, each app process creates a corresponding number of threads to handle requests.

The default value is 1.

thread_stack_size

Integer that defines the stack size of a worker thread (in bytes, multiple of memory page size; the minimum value is usually architecture specific).

The default value is system dependent and can be set with ulimit -s <SIZE_KB>.

Example:

{
    "type": "perl",
    "script": "/www/bugtracker/app.psgi",
    "working_directory": "/www/bugtracker",
    "processes": 10,
    "user": "www",
    "group": "www"
}

Note

For Perl-based examples of Perl, see our Bugzilla and Catalyst howtos or a basic sample.

PHP§

First, make sure to install Unit along with the PHP language module.

Besides common options, you have the following:

OptionDescription
root (required)Base directory of your PHP app’s file structure. All URI paths are relative to this value.
index

Filename appended to any URI paths ending with a slash; applies if script is omitted.

The default value is index.php.

optionsObject that defines the php.ini location and options.
targetsObject that defines application sections with custom root, script, and index values.
scriptFilename of a root-based PHP script that Unit uses to serve all requests to the app.

The index and script options enable two modes of operation:

  • If script is set, all requests to the application are handled by the script you provide.
  • Otherwise, the requests are served according to their URI paths; if script name is omitted, index is used.

You can customize php.ini via the options object:

OptionDescription
filePathname of the php.ini file with PHP configuration directives.
admin, userObjects for extra directives. Values in admin are set in PHP_INI_SYSTEM mode, so the app can’t alter them; user values are set in PHP_INI_USER mode and may be updated in runtime.

Directives from php.ini are overridden by settings supplied in admin and user objects.

Note

Values in options must be strings (for example, "max_file_uploads": "4", not "max_file_uploads": 4); for boolean flags, use "0" and "1" only. For details about PHP_INI_* modes, see the PHP docs.

Note

Unit implements the fastcgi_finish_request() function in a manner similar to PHP-FPM.

Example:

{
    "type": "php",
    "processes": 20,
    "root": "/www/blogs/scripts/",
    "user": "www-blogs",
    "group": "www-blogs",

    "options": {
        "file": "/etc/php.ini",
        "admin": {
            "memory_limit": "256M",
            "variables_order": "EGPCS",
            "expose_php": "0"
        },
        "user": {
            "display_errors": "0"
        }
    }
}

Targets§

You can configure up to 254 individual entry points for a single PHP application:

{
    "applications": {
        "php-app": {
            "type": "php",
            "targets": {
                "foo": {
                    "script": "foo.php",
                    "root": "/www/apps/php-app/foo/"
                },

                "bar": {
                    "script": "bar.php",
                    "root": "/www/apps/php-app/bar/"
                }
            }
        }
    }
}

Each target is an object that specifies root and optionally index or script just like a common application does. Targets can be used by the pass options in listeners and routes to serve requests:

{
    "listeners": {
        "127.0.0.1:8080": {
            "pass": "applications/php-app/foo"
        },

        "127.0.0.1:80": {
            "pass": "routes"
        }
    },

    "routes": [
        {
            "match": {
                "uri": "/bar"
            },

            "action": {
                "pass": "applications/php-app/bar"
            }
        }
    ]
}

App-wide settings (isolation, limits, options, processes) are shared by all targets within the app.

Warning

If you specify targets, there should be no root, index, or script defined at the application level.

Note

For PHP-based examples, see our CakePHP, CodeIgniter, DokuWiki, Drupal, Laravel, Matomo, MediaWiki, MODX, NextCloud, phpBB, Symfony, WordPress, and Yii howtos or a basic sample.

Python§

First, make sure to install Unit along with the Python language module.

Besides common options, you have the following:

OptionDescription
module (required)Application module name. The module itself is imported just like in Python.
callable

Name of the callable in module that Unit uses to run the app.

The default value is application.

home

Path to the app’s virtual environment. Absolute or relative to working_directory.

Note

The Python version used to run the app depends on the type value; Unit ignores the command-line interpreter from the virtual environment for performance considerations.

pathString or array of strings that represent additional Python module lookup paths; these values are prepended to sys.path.
protocolHint to tell Unit that the app uses a certain interface; can be asgi or wsgi.
targetsObject that defines application sections with custom module and callable values.
threads

Integer that sets the number of worker threads per app process. When started, each app process creates a corresponding number of threads to handle requests.

The default value is 1.

thread_stack_size

Integer that defines the stack size of a worker thread (in bytes, multiple of memory page size; the minimum value is usually architecture specific).

The default value is system dependent and can be set with ulimit -s <SIZE_KB>.

Example:

{
    "type": "python",
    "processes": 10,
    "working_directory": "/www/store/",
    "path": "/www/store/cart/",
    "home": "/www/store/.virtualenv/",
    "module": "wsgi",
    "callable": "app",
    "user": "www",
    "group": "www"
}

You can provide the callable in two forms. The first one uses WSGI (PEP 333 or PEP 3333):

def application(environ, start_response):
    start_response('200 OK', [('Content-Type', 'text/plain')])
    yield b'Hello, WSGI\n'

The second one, supported for Python 3.5+, uses ASGI:

async def application(scope, receive, send):

    await send({
        'type': 'http.response.start',
        'status': 200
    })

    await send({
        'type': 'http.response.body',
        'body': b'Hello, ASGI\n'
    })

Note

Legacy two-callable ASGI 2.0 applications were not supported prior to Unit 1.21.0.

Choose either one according to your needs; Unit will attempt to infer your choice automatically. If automatic inference fails, use the protocol option to name the interface explicitly.

Targets§

You can configure up to 254 individual entry points for a single Python application:

{
    "applications": {
        "python-app": {
            "type": "python",
            "path": "/www/apps/python-app/",
            "targets": {
                "foo": {
                    "module": "foo.wsgi",
                    "callable": "foo"
                },

                "bar": {
                    "module": "bar.wsgi",
                    "callable": "bar"
                }
            }
        }
    }
}

Each target is an object that specifies module and optionally callable just like a common application does. Targets can be used by the pass options in listeners and routes to serve requests:

{
    "listeners": {
        "127.0.0.1:8080": {
            "pass": "applications/python-app/foo"
        },

        "127.0.0.1:80": {
            "pass": "routes"
        }
    },

    "routes": [
        {
            "match": {
                "uri": "/bar"
            },

            "action": {
                "pass": "applications/python-app/bar"
            }
        }
    ]
}

The home, path, protocol, threads, and thread_stack_size settings are shared by all targets in the app.

Warning

If you specify targets, there should be no module or callable defined at the application level. Moreover, you can’t combine WSGI and ASGI targets within a single app.

Note

For Python-based examples, see our Bottle, Datasette, Django, Django Channels, FastAPI, Flask, Guillotina, Mercurial, MoinMoin, Plone, Pyramid, Quart, Responder, Review Board, Sanic, Starlette, Trac, and Zope howtos or a basic sample.

Ruby§

First, make sure to install Unit along with the Ruby language module.

Note

Unit uses the Rack interface to run Ruby scripts; you need to have it installed as well:

$ gem install rack

Besides common options, you have the following:

OptionDescription
script (required)Rack script pathname, including the .ru extension: /www/rubyapp/script.ru.
threads

Integer that sets the number of worker threads per app process. When started, each app process creates a corresponding number of threads to handle requests.

The default value is 1.

Example:

{
    "type": "ruby",
    "processes": 5,
    "user": "www",
    "group": "www",
    "script": "/www/cms/config.ru"
}

Note

For Ruby-based examples, see our Ruby on Rails and Redmine howtos or a basic sample.

Settings§

Unit has a global settings configuration object that stores instance-wide preferences. Its http option fine-tunes the handling of HTTP requests from the clients:

OptionDescription
header_read_timeout

Maximum number of seconds to read the header of a client’s request. If Unit doesn’t receive the entire header from the client within this interval, it responds with a 408 Request Timeout error.

The default value is 30.

body_read_timeout

Maximum number of seconds to read data from the body of a client’s request. It limits the interval between consecutive read operations, not the time to read the entire body. If Unit doesn’t receive any data from the client within this interval, it responds with a 408 Request Timeout error.

The default value is 30.

send_timeout

Maximum number of seconds to transmit data in the response to a client. It limits the interval between consecutive transmissions, not the entire response transmission. If the client doesn’t receive any data within this interval, Unit closes the connection.

The default value is 30.

idle_timeout

Maximum number of seconds between requests in a keep-alive connection. If no new requests arrive within this interval, Unit responds with a 408 Request Timeout error and closes the connection.

The default value is 180.

max_body_size

Maximum number of bytes in the body of a client’s request. If the body size exceeds this value, Unit responds with a 413 Payload Too Large error and closes the connection.

The default value is 8388608 (8 MB).

staticObject that configures static asset handling, containing a single object named mime_types. In turn, mime_types defines specific MIME types as options. An option’s value can be a string or an array of strings; each string must specify a filename extension or a specific filename that is included in the MIME type.
discard_unsafe_fields

Controls the parsing mode of header field names. If set to true, Unit only processes headers with names consisting of alphanumeric characters and hyphens (-); otherwise, all valid RFC 7230 header fields are processed.

The default value is true.

Example:

{
    "settings": {
        "http": {
            "header_read_timeout": 10,
            "body_read_timeout": 10,
            "send_timeout": 10,
            "idle_timeout": 120,
            "max_body_size": 6291456,
            "static": {
                "mime_types": {
                    "text/plain": [
                        ".log",
                        "README",
                        "CHANGES"
                    ]
                }
            },
            "discard_unsafe_fields": false
        }
    }
}

Note

Built-in support for MIME types includes .aac, .apng, .atom, .avi, .avif, avifs, .bin, .css, .deb, .dll, .exe, .flac, .gif, .htm, .html, .ico, .img, .iso, .jpeg, .jpg, .js, .json, .md, .mid, .midi, .mp3, .mp4, .mpeg, .mpg, .msi, .ogg, .otf, .pdf, .php, .png, .rpm, .rss, .rst, .svg, .ttf, .txt, .wav, .webm, .webp, .woff2, .woff, .xml, and .zip. Built-ins can be overridden, and new types can be added:

# curl -X PUT -d '{"text/x-code": [".c", ".h"]}' /path/to/control.unit.sock \
       http://localhost/config/settings/http/static/mime_types
{
       "success": "Reconfiguration done."
}

Access Log§

To enable access logging, specify the log file path in the access_log option of the config object.

In the example below, all requests will be logged to /var/log/access.log:

# curl -X PUT -d '"/var/log/access.log"' \
       --unix-socket /path/to/control.unit.sock \
       http://localhost/config/access_log

    {
        "success": "Reconfiguration done."
    }

The log is written in the Combined Log Format. Example of a log line:

127.0.0.1 - - [21/Oct/2015:16:29:00 -0700] "GET / HTTP/1.1" 200 6022 "http://example.com/links.html" "Godzilla/5.0 (X11; Minix i286) Firefox/42"

Certificate Management§

To set up SSL/TLS access for your application, upload a .pem file containing your certificate chain and private key to Unit. Next, reference the uploaded bundle in the listener’s configuration. After that, the listener’s application becomes accessible via SSL/TLS.

Note

For the details of certificate issuance and renewal in Unit, see an example in TLS with Certbot.

First, create a .pem file with your certificate chain and private key:

$ cat cert.pem ca.pem key.pem > bundle.pem

Usually, your website’s certificate (optionally followed by the intermediate CA certificate) is enough to build a certificate chain. If you add more certificates to your chain, order them leaf to root.

Upload the resulting bundle file to Unit’s certificate storage under a suitable name (in this case, bundle):

# curl -X PUT --data-binary @bundle.pem --unix-socket \
       /path/to/control.unit.sock http://localhost/certificates/bundle

    {
        "success": "Certificate chain uploaded."
    }

Warning

Don’t use -d for file upload with curl; this option damages .pem files. Use the --data-binary option when uploading file-based data to avoid data corruption.

Internally, Unit stores the uploaded certificate bundles along with other configuration data in its state subdirectory; Unit’s control API maps them to a separate configuration section, aptly named certificates:

{
    "certificates": {
        "bundle": {
            "key": "RSA (4096 bits)",
            "chain": [
                {
                    "subject": {
                        "common_name": "example.com",
                        "alt_names": [
                            "example.com",
                            "www.example.com"
                        ],

                        "country": "US",
                        "state_or_province": "CA",
                        "organization": "Acme, Inc."
                    },

                    "issuer": {
                        "common_name": "intermediate.ca.example.com",
                        "country": "US",
                        "state_or_province": "CA",
                        "organization": "Acme Certification Authority"
                    },

                    "validity": {
                        "since": "Sep 18 19:46:19 2018 GMT",
                        "until": "Jun 15 19:46:19 2021 GMT"
                    }
                },

                {
                    "subject": {
                        "common_name": "intermediate.ca.example.com",
                        "country": "US",
                        "state_or_province": "CA",
                        "organization": "Acme Certification Authority"
                    },

                    "issuer": {
                        "common_name": "root.ca.example.com",
                        "country": "US",
                        "state_or_province": "CA",
                        "organization": "Acme Root Certification Authority"
                    },

                    "validity": {
                        "since": "Feb 22 22:45:55 2016 GMT",
                        "until": "Feb 21 22:45:55 2019 GMT"
                    }
                }
            ]
        }
    }
}

Note

You can access individual certificates in your chain, as well as specific alternative names, by their indexes:

# curl -X GET --unix-socket /path/to/control.unit.sock \
       http://localhost/certificates/bundle/chain/0/
# curl -X GET --unix-socket /path/to/control.unit.sock \
       http://localhost/certificates/bundle/chain/0/subject/alt_names/0/

Next, add the uploaded bundle to a listener; the resulting control API configuration may look like this:

{
    "certificates": {
        "bundle": {
            "key": "<key type>",
            "chain": ["<certificate chain, omitted for brevity>"]
        }
    },

    "config": {
        "listeners": {
            "*:443": {
                "pass": "applications/wsgi-app",
                "tls": {
                    "certificate": "bundle"
                }
            }
        },

        "applications": {
            "wsgi-app": {
                "type": "python",
                "module": "wsgi",
                "path": "/usr/www/wsgi-app/"
            }
        }
    }
}

Now you’re solid; the application is accessible via SSL/TLS:

$ curl -v https://127.0.0.1
    ...
    * TLSv1.2 (OUT), TLS handshake, Client hello (1):
    * TLSv1.2 (IN), TLS handshake, Server hello (2):
    * TLSv1.2 (IN), TLS handshake, Certificate (11):
    * TLSv1.2 (IN), TLS handshake, Server finished (14):
    * TLSv1.2 (OUT), TLS handshake, Client key exchange (16):
    * TLSv1.2 (OUT), TLS change cipher, Client hello (1):
    * TLSv1.2 (OUT), TLS handshake, Finished (20):
    * TLSv1.2 (IN), TLS change cipher, Client hello (1):
    * TLSv1.2 (IN), TLS handshake, Finished (20):
    * SSL connection using TLSv1.2 / AES256-GCM-SHA384
    ...

Finally, you can DELETE a certificate bundle that you don’t need anymore from the storage:

# curl -X DELETE --unix-socket /path/to/control.unit.sock \
       http://localhost/certificates/bundle

    {
        "success": "Certificate deleted."
    }

Note

You can’t delete certificate bundles still referenced in your configuration, overwrite existing bundles using PUT, or (obviously) delete non-existent ones.

Full Example§

{
    "certificates": {
        "example.com": {
            "key": "RSA (4096 bits)",
            "chain": [
                {
                    "subject": {
                        "common_name": "example.com",
                        "alt_names": [
                            "example.com",
                            "www.example.com"
                        ],

                        "country": "US",
                        "state_or_province": "CA",
                        "organization": "Acme, Inc."
                    },

                    "issuer": {
                        "common_name": "intermediate.ca.example.com",
                        "country": "US",
                        "state_or_province": "CA",
                        "organization": "Acme Certification Authority"
                    },

                    "validity": {
                        "since": "Sep 18 19:46:19 2018 GMT",
                        "until": "Jun 15 19:46:19 2021 GMT"
                    }
                },

                {
                    "subject": {
                        "common_name": "intermediate.ca.example.com",
                        "country": "US",
                        "state_or_province": "CA",
                        "organization": "Acme Certification Authority"
                    },

                    "issuer": {
                        "common_name": "root.ca.example.com",
                        "country": "US",
                        "state_or_province": "CA",
                        "organization": "Acme Root Certification Authority"
                    },

                    "validity": {
                        "since": "Feb 22 22:45:55 2016 GMT",
                        "until": "Feb 21 22:45:55 2019 GMT"
                    }
                }
            ]
        },

        "example.org": {
            "key": "RSA (4096 bits)",
            "chain": [
                {
                    "subject": {
                        "common_name": "example.org",
                        "alt_names": [
                            "example.org",
                            "www.example.org"
                        ],

                        "country": "US",
                        "state_or_province": "CA",
                        "organization": "Acme, Inc."
                    },

                    "issuer": {
                        "common_name": "intermediate.ca.example.org",
                        "country": "US",
                        "state_or_province": "CA",
                        "organization": "Acme Certification Authority"
                    },

                    "validity": {
                        "since": "Sep 18 19:46:19 2018 GMT",
                        "until": "Jun 15 19:46:19 2021 GMT"
                    }
                },

                {
                    "subject": {
                        "common_name": "intermediate.ca.example.org",
                        "country": "US",
                        "state_or_province": "CA",
                        "organization": "Acme Certification Authority"
                    },

                    "issuer": {
                        "common_name": "root.ca.example.org",
                        "country": "US",
                        "state_or_province": "CA",
                        "organization": "Acme Root Certification Authority"
                    },

                    "validity": {
                        "since": "Feb 22 22:45:55 2016 GMT",
                        "until": "Feb 21 22:45:55 2019 GMT"
                    }
                }
            ]
        }
    },

    "config": {
        "settings": {
            "http": {
                "header_read_timeout": 10,
                "body_read_timeout": 10,
                "send_timeout": 10,
                "idle_timeout": 120,
                "max_body_size": 6291456,
                "static": {
                    "mime_types": {
                        "text/plain": [
                             ".log",
                             "README",
                             "CHANGES"
                        ]
                    }
                },
                "discard_unsafe_fields": false
            }
        },

        "listeners": {
            "*:8000": {
                "pass": "routes",
                "tls": {
                    "certificate": [
                        "example.com",
                        "example.org"
                    ],
                    "conf_commands" : {
                         "ciphersuites": "TLS_CHACHA20_POLY1305_SHA256"
                    }
                }
            },

            "127.0.0.1:8001": {
                "pass": "applications/drive"
            },

            "*:8080": {
                "pass": "upstreams/rr-lb"
            }
        },

        "routes": [
            {
                "match": {
                    "uri": "/admin/*",
                    "scheme": "https",
                    "arguments": {
                        "mode": "strict",
                        "access": "!raw"
                    },

                    "cookies": {
                        "user_role": "admin"
                    }
                },

                "action": {
                    "pass": "applications/cms"
                }
            },
            {
                "match": {
                    "host": "admin.emea-*.*.example.com",
                    "source": "*:8000-9000"
                },

                "action": {
                    "pass": "applications/blogs/admin"
                }
            },
            {
                "match": {
                    "host": ["blog.example.com", "blog.*.org"],
                    "source": "*:8000-9000"
                },

                "action": {
                    "pass": "applications/blogs/core"
                }
            },
            {
                "match": {
                    "host": "example.com",
                    "source": "127.0.0.0-127.0.0.255:8080-8090",
                    "uri": "/chat/*"
                },

                "action": {
                    "pass": "applications/chat"
                }
            },
            {
                "match": {
                    "host": "example.com",
                    "source": [
                        "10.0.0.0/7:1000",
                        "10.0.0.0/32:8080-8090"
                    ]
                },

                "action": {
                    "pass": "applications/store"
                }
            },
            {
                "match": {
                    "host": "extwiki.example.com"
                },

                "action": {
                    "pass": "applications/wiki/external"
                }
            },
            {
                "match": {
                    "host": "intwiki.example.com"
                },

                "action": {
                    "pass": "applications/wiki/internal"
                }
            },
            {
                "match": {
                     "uri": "/legacy/*"
                },

                "action": {
                    "return": 301,
                    "location": "https://legacy.example.com"
                }
            },
            {
                "match": {
                    "scheme": "http"
                },

                "action": {
                    "proxy": "http://127.0.0.1:8080"
                }
            },
            {
                "action": {
                    "share": "/www/data/static/",
                    "chroot": "/www/data/",
                    "traverse_mounts": false,
                    "follow_symlinks": false,
                    "types": [
                        "image/*",
                        "video/*",
                        "application/json"
                    ],
                    "fallback": {
                        "proxy": "http://127.0.0.1:9000"
                    }
                }
            }
        ],

        "applications": {
            "blogs": {
                "type": "php",
                "targets": {
                    "admin": {
                        "root": "/www/blogs/admin/",
                        "script": "index.php"
                    },

                    "core" : {
                        "root": "/www/blogs/scripts/"
                    }
                },

                "limits": {
                    "timeout": 10,
                    "requests": 1000
                },

                "options": {
                    "file": "/etc/php.ini",
                    "admin": {
                        "memory_limit": "256M",
                        "variables_order": "EGPCS",
                        "expose_php": "0"
                    },

                    "user": {
                        "display_errors": "0"
                    }
                },

                "processes": 4
            },

            "chat": {
                "type": "external",
                "executable": "bin/chat_app",
                "group": "www-chat",
                "user": "www-chat",
                "working_directory": "/www/chat/",
                "isolation": {
                    "namespaces": {
                        "cgroup": false,
                        "credential": true,
                        "mount": false,
                        "network": false,
                        "pid": false,
                        "uname": false
                    },

                    "uidmap": [
                        {
                            "host": 1000,
                            "container": 0,
                            "size": 1000
                        }
                    ],

                    "gidmap": [
                        {
                            "host": 1000,
                            "container": 0,
                            "size": 1000
                        }
                    ],

                    "automount": {
                        "language_deps": false,
                        "procfs": false,
                        "tmpfs": false
                    }
                }
            },

            "cms": {
                "type": "ruby",
                "script": "/www/cms/main.ru",
                "working_directory": "/www/cms/"
            },

            "drive": {
                "type": "perl",
                "script": "app.psgi",
                "threads": 2,
                "thread_stack_size": 4096,
                "working_directory": "/www/drive/",
                "processes": {
                    "max": 10,
                    "spare": 5,
                    "idle_timeout": 20
                }
            },

            "store": {
                "type": "java",
                "webapp": "/www/store/store.war",
                "classpath": ["/www/store/lib/store-2.0.0.jar"],
                "options": ["-Dlog_path=/var/log/store.log"]
            },

            "wiki": {
                "type": "python",
                "protocol": "asgi",
                "targets": {
                    "internal": {
                        "module": "internal.asgi"
                    },

                    "external": {
                        "module": "external.asgi"
                    }
                },

                "environment": {
                    "DJANGO_SETTINGS_MODULE": "wiki.settings.prod",
                    "DB_ENGINE": "django.db.backends.postgresql",
                    "DB_NAME": "wiki",
                    "DB_HOST": "127.0.0.1",
                    "DB_PORT": "5432"
                },

                "path": "/www/wiki/",
                "processes": 10
            }
        },

        "upstreams": {
            "rr-lb": {
                "servers": {
                    "192.168.1.100:8080": { },
                    "192.168.1.101:8080": {
                        "weight": 2
                    }
                }
            }
        },

        "access_log": "/var/log/access.log"
    }
}
Improve this page