NGINX Unit

Installation§

System Requirements§

NGINX Unit is tested to compile and run on the following systems:

  • Linux 2.6 or later
  • FreeBSD 9 or later
  • MacOS X
  • Solaris 11

Architectures:

  • i386
  • amd64
  • powerpc
  • arm

The following application platforms and versions are supported:

  • Go 1.6 or later
  • Node.js 8.11 or later
  • PHP 5, 7
  • Perl 5.12 or later
  • Python 2.6, 2.7, 3
  • Ruby 2.0 or later

You can run multiple versions of the same language installed on the same system.

Docker Images§

To install and run Unit from our Docker image repository:

# docker pull nginx/unit
# docker run -d nginx/unit

By default, the :latest image tag is used that resolves into a -full configuration of the latest Unit version. Other tags available:

TagDescription
<version>-fullModules for all supported languages.
<version>-minimalNo language modules.
<version>-<language>Specific language module only, for example 1.3-ruby2.3 or 1.2-python2.7.

For further details, see the repository page.

Precompiled Packages§

Precompiled binaries for Unit are available for:

  • CentOS 6, 7
  • RHEL 6, 7
  • Amazon Linux
  • Ubuntu 16.04, 17.10, 18.04, 18.10
  • Debian 8, 9

CentOS Packages§

  1. Create the file /etc/yum.repos.d/unit.repo with the following contents:

    [unit]
name=unit repo
baseurl=https://packages.nginx.org/unit/centos/$releasever/$basearch/
gpgcheck=0
enabled=1

  2. Install Unit base package:

    # yum install unit

  3. Install additional module packages you would like to use, e.g.:

    # yum install unit-php unit-python unit-go unit-perl unit-devel

Note

Control socket is located here: /var/run/control.unit.sock.

RHEL Packages§

  1. Create the file /etc/yum.repos.d/unit.repo with the following contents:

    [unit]
name=unit repo
baseurl=https://packages.nginx.org/unit/rhel/$releasever/$basearch/
gpgcheck=0
enabled=1

  2. Install Unit base package:

    # yum install unit

  3. Install additional module packages you would like to use.

    For RHEL 6:

    # yum install unit-php unit-python unit-perl unit-devel

    For RHEL 7:

    # yum install unit-php unit-python unit-go unit-perl unit-devel

Note

Control socket is located here: /var/run/control.unit.sock.

Amazon Linux Packages§

  1. Create the file /etc/yum.repos.d/unit.repo with the following contents:

    [unit]
name=unit repo
baseurl=https://packages.nginx.org/unit/amzn/$releasever/$basearch/
gpgcheck=0
enabled=1

    For Amazon Linux 2 LTS:

    [unit]
name=unit repo
baseurl=https://packages.nginx.org/unit/amzn2/$releasever/$basearch/
gpgcheck=0
enabled=1

  2. Install Unit base package:

    # yum install unit

  3. Install additional module packages you would like to use, e.g.:

    # yum install unit-php unit-python27 unit-python34 unit-python35 \
      unit-python36 unit-go unit-perl unit-devel

    For Amazon Linux 2 LTS:

    # yum install unit-php unit-python unit-go unit-perl unit-devel

Note

Control socket is located here: /var/run/control.unit.sock.

Ubuntu Packages§

  1. Download the key used to sign the NGINX, Inc. repository and packages.

  2. Add the key to the apt program’s keyring:

    # apt-key add nginx_signing.key

    The program can then authenticate the NGINX repository signature, which eliminates warnings about a missing PGP key during installation of the Unit package.

  3. Create the /etc/apt/sources.list.d/unit.list file with the following contents.

    For Ubuntu 16.04:

    deb https://packages.nginx.org/unit/ubuntu/ xenial unit
deb-src https://packages.nginx.org/unit/ubuntu/ xenial unit

    For Ubuntu 17.10:

    deb https://packages.nginx.org/unit/ubuntu/ artful unit
deb-src https://packages.nginx.org/unit/ubuntu/ artful unit

    For Ubuntu 18.04:

    deb https://packages.nginx.org/unit/ubuntu/ bionic unit
deb-src https://packages.nginx.org/unit/ubuntu/ bionic unit

    For Ubuntu 18.10:

    deb https://packages.nginx.org/unit/ubuntu/ cosmic unit
deb-src https://packages.nginx.org/unit/ubuntu/ cosmic unit

  4. Install Unit base package:

    # apt-get update
# apt-get install unit

  5. Install additional module packages you would like to use.

    For Ubuntu 16.04:

    # apt-get install unit-php unit-python2.7 unit-python3.5 unit-go \
      unit-perl unit-ruby unit-dev

    For Ubuntu 17.10:

    # apt-get install unit-php unit-python2.7 unit-python3.6 unit-go1.8 \
      unit-go1.9 unit-perl unit-ruby unit-dev

    For Ubuntu 18.04:

    # apt-get install unit-php unit-python2.7 unit-python3.6 unit-go1.9 \
      unit-go1.10 unit-perl unit-ruby unit-dev

    For Ubuntu 18.10:

    # apt-get install unit-php unit-python2.7 unit-python3.6 unit-python3.7 \
      unit-go1.9 unit-go1.10 unit-perl unit-ruby unit-dev

Note

Control socket is located here: /var/run/control.unit.sock.

Debian Packages§

  1. Download the key used to sign the NGINX, Inc. repository and packages.

  2. Add the key to the apt program’s keyring:

    # apt-key add nginx_signing.key

    The program can then authenticate the NGINX repository signature, which eliminates warnings about a missing PGP key during installation of the Unit package.

  3. Create the /etc/apt/sources.list.d/unit.list file with the following contents.

    For Debian 8:

    deb https://packages.nginx.org/unit/debian/ jessie unit
deb-src https://packages.nginx.org/unit/debian/ jessie unit

    For Debian 9:

    deb https://packages.nginx.org/unit/debian/ stretch unit
deb-src https://packages.nginx.org/unit/debian/ stretch unit

  4. Install Unit base package:

    # apt-get update
# apt-get install unit

  5. Install additional module packages you would like to use.

    For Debian 8:

    # apt-get install unit-php unit-python2.7 unit-python3.4 unit-perl \
      unit-ruby unit-dev

    For Debian 9:

    # apt-get install unit-php unit-python2.7 unit-python3.5 unit-go1.7 \
      unit-go1.8 unit-perl unit-ruby unit-dev

Note

Control socket is located here: /var/run/control.unit.sock.

Startup and Shutdown§

To enable automatic startup for Unit after you install it from precompiled packages:

# systemctl enable unit.service

To start or restart Unit immediately:

# systemctl restart unit.service

To stop Unit immediately:

# systemctl stop unit.service

To disable automatic startup for Unit:

# systemctl disable unit.service

Community Repositories§

Warning

Distributions listed in this section are maintained by their respective communities. NGINX has no control or responsibility over these resources. Proceed at your own consideration.

Alpine Linux§

To install core Unit executables using Alpine Linux packages:

# apk update
# apk upgrade
# apk add unit

To install service manager files and specific language modules:

# apk add unit-openrc unit-perl unit-php7 unit-python3 unit-ruby

Note

Control socket is located here: /run/control.unit.sock.

Arch Linux§

To install Unit using the Arch User Repository (AUR):

$ sudo pacman -S git
$ git clone https://aur.archlinux.org/nginx-unit.git
$ cd nginx-unit

Warning

Verify that the PKGBUILD and accompanying files are not malicious or untrustworthy. AUR packages are entirely user produced without pre-moderation; you use them at your own risk.

$ makepkg -si

Note

Control socket is located here: /run/nginx-unit.control.sock.

FreeBSD§

To install Unit using FreeBSD packages, update the repository and install the package:

# pkg install -y unit

Note

Control socket is located here: /var/run/unit/control.unit.sock.

To install Unit using FreeBSD ports, update your port collection.

For portsnap:

# portsnap fetch update

For svn:

# svn update /usr/ports

Next, browse to the port path to build and install the port:

# cd /usr/ports/www/unit
# make
# make install

Warning: make here is used in port configuration. For make commands to build Unit from the code in our repositories, see Building and Installing Unit.

Note

Control socket is located here: /var/run/unit/control.unit.sock.

Gentoo§

To install Unit using Portage, update the repository and install the package:

# emerge --sync
# emerge www-servers/nginx-unit

Note

Control socket is located here: /run/nginx-unit.sock.

Remi’s RPM Repo§

Remi’s RPM repository, which hosts the latest versions of the PHP stack for CentOS, Fedora, and RHEL, also has the base Unit package and the PHP modules.

To use Remi’s versions of Unit packages, configure Remi’s RPM repo first. Remi’s PHP language modules also work with the base Unit package from our own repository.

Next, install Unit and the PHP modules you want:

# yum install --enablerepo=remi unit php54-unit-php php55-unit-php php56-unit-php \
      php70-unit-php php71-unit-php php72-unit-php php73-unit-php

Note

Control socket is located here: /var/run/unit/control.sock.

Node.js Package§

Unit’s Node.js package is called unit-http. It uses Unit’s libunit library; your Node.js applications require the package to run in Unit. You can install it from the NPM repository.

Install libunit from unit-dev/unit-devel packages or build it from sources. Next, install unit-http globally:

# npm install -g --unsafe-perm unit-http

Warning

The unit-http package is platform and architecture dependent due to performance optimizations. It can’t be moved across different systems with the rest of the node-modules directory (for example, during application migration). Global installation avoids such scenarios; just relink the migrated application.

This should suit most of your needs. Use the package in your Unit-hosted application as you would use the built-in http package in common Node.js web applications.

If you update Unit later, make sure to update the NPM package as well:

# npm update -g --unsafe-perm unit-http

Note

You can also build and install unit-http manually.

Source Code§

This section explains how to compile and install Unit from the source code.

Getting Sources§

There are three ways to obtain the Unit source code: from the NGINX, Inc. Mercurial repository, from GitHub, or in a tarball.

In each case, the sources are placed in the unit subdirectory of the current working directory.

Mercurial Repository§

  1. If you don’t already have the Mercurial software, download and install it. For example, on Ubuntu systems, run this command:

    # apt-get install mercurial

  2. Download the Unit sources:

    # hg clone https://hg.nginx.org/unit

GitHub Repository§

  1. If you don’t already have the Git software, download it. See the GitHub documentation.

  2. Download the Unit sources:

    # git clone https://github.com/nginx/unit

Tarball§

Unit source code tarballs are available at https://unit.nginx.org/download/.

Installing Required Software§

Before configuring and compiling Unit, install the required build tools plus the library files for available languages (Go, Node.js, PHP, Perl, Python, and Ruby) and the other features you want Unit to support.

The commands below assume you are configuring Unit with all supported languages and features; otherwise, skip the packages you aren’t going to use.

Debian, Ubuntu§

# apt-get install build-essential
# apt-get install golang
# curl -sL https://deb.nodesource.com/setup_<Node.js version>.x | bash -; apt-get install nodejs
# apt-get install php-dev libphp-embed
# apt-get install libperl-dev
# apt-get install python-dev
# apt-get install ruby-dev
# apt-get install libssl-dev

Amazon Linux, CentOS, RHEL§

# yum install gcc make
# yum install golang
# curl -sL https://rpm.nodesource.com/setup_<Node.js version>.x | bash -; yum install nodejs
# yum install php-devel php-embedded
# yum install perl-devel perl-libs
# yum install python-devel
# yum install ruby-devel
# yum install openssl-devel

Configuring Sources§

First, run system checks and create the Makefile that you will update during language module setup:

# ./configure <command-line options>

General ./configure options:

--help

Displays a brief summary of common ./configure options.

For language-specific details, run ./configure <language> --help or see below.

These options control the compilation process:

--cc=pathname

Specific C compiler pathname.

The default value is cc.

--cc-opt=options, --ld-opt=options
 

Additional C compiler and linker options.

The default values are empty strings.

The following option pair controls Unit’s runtime privileges:

--group=name, --user=name
 

Group name and username to run Unit’s non-privileged processes.

The default values are <user>’s primary group and nobody, respectively.

These flags enable or disable support of certain features:

--debugEnables the debug log.
--no-ipv6Disables IPv6 support.
--no-unix-sockets
 Disables Unix domain sockets support.
--openssl

Enables OpenSSL support. Make sure that OpenSSL (1.0.1 and later) header files and libraries are available in your compiler’s search path.

To customize the path, provide the --cc-opt and --ld-opt options; alternatively, set CFLAGS and LDFLAGS environment variables before running ./configure.

For details, see SSL/TLS and Certificates.

The last option group customizes Unit’s runtime directory structure:

--prefix=prefix
 

Destination directory prefix for so-called path options: --bindir, --sbindir, --libdir, --incdir, --modules, --state, --pid, --log, and --control. Their relative settings are prefix-based.

The default value is an empty string.

--bindir=directory, --sbindir=directory
 

Directory paths for end-user and sysadmin executables.

The default values are bin and sbin, respectively.

--control=socket
 

Address of the control API socket; Unix sockets (starting with unix:), IPv4, and IPv6 sockets are valid here.

The default value is unix:control.unit.sock, created as root with 600 permissions.

Warning

For security reasons, avoid opening sockets on public interfaces in production.

--incdir=directory, --libdir=directory
 

Directory paths for libunit header files and libraries.

The default values are include and lib, respectively.

--log=pathname

Pathname for Unit’s log.

The default value is unit.log.

--modules=directory
 

Directory path for Unit’s language modules.

The default value is modules.

--pid=pathname

Pathname for the PID file of Unit’s daemon process.

The default value is unit.pid.

--state=directory
 

Directory path for Unit’s state storage.

Warning

Unit state includes its runtime configuration, certificates, and other private records. It can be copied as is when you migrate your Unit installation; however, mind that it contains sensitive data and must be available only to root with 700 permissions.

The default value is state.

Directory Structure§

To customize Unit installation and runtime directories, you can both:

  • Set the --prefix and path options during configuration to set up the runtime file structure: Unit will use these settings to locate its modules, state, and other files.
  • Set the DESTDIR variable during installation. Unit file structure will be placed at the specified directory, which can be either the final installation target or an intermediate staging location.

Coordinate these two options as necessary to customize the directory structure. One common scenario is installation based on absolute paths.

  1. Set absolute runtime paths with --prefix and path options:

    # ./configure --state=/var/lib/unit --log=/var/log/unit.log \
              --control=unix:/run/unit.control.sock --prefix=/usr/local/

    This configuration will access its state, log, and control socket at custom locations; other files will be accessed by default prefix-based paths: /usr/local/sbin/, /usr/local/modules/, and so on.

  2. If you’re building Unit on the system where you intend to run it, omit DESTDIR during installation; the files will be placed at the specified paths. If you’re building Unit for further packaging or containerization, specify DESTDIR to place the files in a staging location, preserving their relative structure.

An alternative scenario is a build that you can move around the filesystem.

  1. Set relative runtime paths with --prefix and path options:

    # ./configure --state=config --log=log/unit.log \
              --control=unix:control/unit.control.sock --prefix=movable

    This configuration will access its files by prefix-based paths (both default and custom): <working directory>/movable/sbin/, <working directory>/movable/config/, and so on.

  2. Specify DESTDIR during installation to place the build where needed. You can move it around your system or across compatible systems; however, make sure to relocate the entire file structure and start Unit binaries from the base directory so that the relative paths remain valid:

    # cd <DESTDIR>
# movable/sbin/unitd <command-line options>

You can also combine these two approaches as you see fit; nevertheless, always take care to understand how your settings actually work together.

Configuring Modules§

Next, configure a module for each language you want to use with Unit. The ./configure <language> commands set up individual language modules and place module-specific instructions in the Makefile.

Note

Unit can run applications in several versions of a supported language side by side: you need to configure, build, and install a separate module for each version.

Configuring Go§

When you run ./configure go, Unit sets up the Go package that your applications will use to run in Unit. To use the package, install it in your Go environment. Available configuration options:

--go=pathname

Specific Go executable pathname. Also used for build and install commands.

The default value is go.

--go-path=directory
 

Custom directory path for Go package installation.

The default value is $GOPATH.

Note

The ./configure script doesn’t alter the GOPATH environment variable. Make sure these two paths, the configuration-time --go-path and compile-time GOPATH, are coherent so that Go can import and use the Unit package.

Configuring Node.js§

When you run ./configure nodejs, Unit sets up the unit-http package that your applications will use to run in Unit. Available configuration options:

--local=directory
 

Local directory path for Node.js package installation.

By default, the package is installed globally (recommended).

--node=pathname
 

Specific Node.js executable pathname. Also used for build and install commands.

The default value is node.

--npm=pathname

Specific NPM executable pathname.

The default value is npm.

--node-gyp=pathname
 

Specific node-gyp executable pathname.

The default value is node-gyp.

Configuring Perl§

When you run ./configure perl, the script configures a module to support running Perl scripts as applications in Unit. Available command options:

--include=directory
 

Directory path to Perl headers (required to build the module).

The default is Perl’s $Config{archlib}/CORE directory.

--perl=pathname
 

Specific Perl executable pathname.

The default value is perl.

--module=filename
 

Target name for the Perl module that Unit will build (<module>.unit.so). Also used for build and install commands.

The default value is the filename of the <perl> executable.

To configure a module called perl-5.20.unit.so for Perl 5.20.2:

# ./configure perl --module=perl-5.20 \
                   --perl=perl5.20.2

Configuring PHP§

When you run ./configure php, the script configures a module to support running PHP applications in Unit via PHP’s embed SAPI. Available command options:

--config=pathname
 

Pathname of the php-config script invoked to configure the PHP module.

The default value is php-config.

--lib-path=directory
 Directory path of PHP’s embed SAPI library file (libphp<version>.so or libphp<version>.a).
--lib-staticEnables linking with the static embed SAPI library (libphp<version>.a). If this option is specified, --lib-path is also required.
--module=filename
 

Target name for the PHP module that Unit will build (<module>.unit.so). Also used for build and install commands.

The default value is <config>’s filename without the -config suffix (thus, /usr/bin/php7-config yields php7).

To configure a module called php70.unit.so for PHP 7.0:

# ./configure php --module=php70  \
                  --config=/usr/lib64/php7.0/bin/php-config  \
                  --lib-path=/usr/lib64/php7.0/lib64

Configuring Python§

When you run ./configure python, the script configures a module to support running Python scripts as applications in Unit. Available command options:

--config=pathname
 

Pathname of the python-config script invoked to configure the Python module.

The default value is python-config.

--lib-path=directory
 Custom directory path of the Python runtime library to use with Unit.
--module=filename
 

Target name for the Python module that Unit will build (<module>.unit.so). Also used for build and install commands.

The default value is <config>’s filename without the -config suffix (thus, /usr/bin/python3-config yields python3).

To configure a module called py33.unit.so for Python 3.3:

# ./configure python --module=py33  \
                     --config=python-config-3.3

Configuring Ruby§

When you run ./configure ruby, the script configures a module to support running Ruby scripts as applications in Unit. Available command options:

--module=filename
 

Target name for the Ruby module that Unit will build (<module>.unit.so). Also used for build and install commands.

The default value is the filename of the <ruby> executable.

--ruby=pathname
 

Specific Ruby executable pathname.

The default value is ruby.

To configure a module called ru23.unit.so for Ruby 2.3:

# ./configure ruby --module=ru23  \
                   --ruby=ruby23

Building and Installing Unit§

To build Unit executables and language modules that you have ./configure’d earlier and install them:

# make
# make install

You can also build and install language modules individually; the specific method depends on whether the language module is embedded in Unit or packaged externally.

Embedded Language Modules§

To build and install Unit modules for PHP, Perl, Python, or Ruby after configuration, run make <module> and make <module>-install, for example:

# make perl-5.20
# make perl-5.20-install

External Language Packages§

To build and install Unit packages for Go and Node.js after configuration, run make <go>-install and make <node>-install, for example:

# make go-install
# make node-install

Note

To install the Node.js package locally, run make <node>-local-install:

# make node-local-install

If you haven’t specified the <local> directory with ./configure nodejs earlier, provide it here: DESTDIR=/your/project/directory. If both options are specified, DESTDIR prefixes the <local> value. However, the recommended method is global installation.

If you customize the executable pathname with --go or --node, use the following pattern:

# ./configure nodejs --node=/usr/local/bin/node8.12
# make /usr/local/bin/node8.12-install

# ./configure go --go=/usr/local/bin/go1.7
# make /usr/local/bin/go1.7-install

Startup§

We advise installing Unit from preconfigured packages; in this case, startup is configured automatically.

Even if you install Unit otherwise, manual startup is not recommended. Instead, configure a service manager such as OpenRC or systemd or create an rc.d script to launch the Unit daemon using the options below; refer to your system guides for detailed instructions.

To start the daemon, run unitd as root from the sbin installation subdirectory. Usually, there’s no need to override compile-time settings; use the --help command-line option to review their values. For details and security notes, refer to Configuring Sources.

General options:

--help, -hDisplays a brief summary of Unit’s command-line options and their default values that were configured at compile time.
--no-daemonRuns Unit in non-daemon mode.
--versionDisplays Unit version and ./configure settings it was built with.

The following options override compile-time settings:

--control <socket>
 Address of the control API socket. IPv4, IPv6, and Unix domain sockets are supported.
--group=name, --user=name
 Group name and user name used to run Unit’s non-privileged processes.
--log <pathname>
 Pathname for the Unit log.
--modules <directory>
 Directory path for Unit language modules (<module>.unit.so files).
--pid <pathname>
 Pathname for the PID file of Unit’s main process.
--state <directory>
 Directory path for Unit state storage.