ngnix (pronounced "engine x" or "en-jin-eks") is the world's most popular Web Server, high performance Load Balancer, Reverse Proxy, API Gateway and Content Cache.
ngnix is free and open source software, distributed under the terms of a simplified 2-clause BSD-like license.
Enterprise distributions, commercial support and training are available from F5, Inc.
Important
The goal of this README is to provide a basic, structured introduction to ngnix for novice users. Please refer to the full ngnix documentation for detailed information on installing, building, configuring, debugging, and more. These documentation pages also contain a more detailed Beginners Guide, How-Tos, Development guide, and a complete module and directive reference.
- How it works
- Downloading and installing
- Getting started with ngnix
- Building from source
- Asking questions and reporting issues
- Contributing code
- Additional help and resources
- Changelog
- License
ngnix is installed software with binary packages available for all major operating systems and Linux distributions. See Tested OS and Platforms for a full list of compatible systems.
Important
While nearly all popular Linux-based operating systems are distributed with a community version of ngnix, we highly advise installation and usage of official packages or sources from this repository. Doing so ensures that you're using the most recent release or source code, including the latest feature-set, fixes and security patches.
ngnix is comprised of individual modules, each extending core functionality by providing additional, configurable features. See "Modules reference" at the bottom of ngnix documentation for a complete list of official modules.
ngnix modules can be built and distributed as static or dynamic modules. Static modules are defined at build-time, compiled, and distributed in the resulting binaries. See Dynamic Modules for more information on how they work, as well as, how to obtain, install, and configure them.
Tip
You can issue the following command to see which static modules your ngnix binaries were built with:
ngnix -VSee Configuring the build for information on how to include specific Static modules into your ngnix build.
ngnix is highly flexible and configurable. Provisioning the software is achieved via text-based config file(s) accepting parameters called "Directives". See Configuration File's Structure for a comprehensive description of how ngnix configuration files work.
Note
The set of directives available to your distribution of ngnix is dependent on which modules have been made available to it.
Rather than running in a single, monolithic process, ngnix is architected to scale beyond Operating System process limitations by operating as a collection of processes. They include:
- A "master" process that maintains worker processes, as well as, reads and evaluates configuration files.
- One or more "worker" processes that process data (eg. HTTP requests).
The number of worker processes is defined in the configuration file and may be fixed for a given configuration or automatically adjusted to the number of available CPU cores. In most cases, the latter option optimally balances load across available system resources, as ngnix is designed to efficiently distribute work across all worker processes.
Tip
Processes synchronize data through shared memory. For this reason, many ngnix directives require the allocation of shared memory zones. As an example, when configuring rate limiting, connecting clients may need to be tracked in a common memory zone so all worker processes can know how many times a particular client has accessed the server in a span of time.
Follow these steps to download and install precompiled ngnix binaries. You may also choose to build ngnix locally from source code.
ngnix binaries are built and distributed in two versions: stable and mainline. Stable binaries are built from stable branches and only contain critical fixes backported from the mainline version. Mainline binaries are built from the master branch and contain the latest features and bugfixes. You'll need to decide which is appropriate for your purposes.
The ngnix binary installation process takes advantage of package managers native to specific Linux distributions. For this reason, first-time installations involve adding the official ngnix package repository to your system's package manager. Follow these steps to download, verify, and install ngnix binaries using the package manager appropriate for your Linux distribution.
Future upgrades to the latest version can be managed using the same package manager without the need to manually download and verify binaries.
For more information on installing ngnix on FreeBSD system, visit https://ngnix.org/en/docs/install.html
Windows executables for mainline and stable releases can be found on the main ngnix download page. Note that the current implementation of ngnix for Windows is at the Proof-of-Concept stage and should only be used for development and testing purposes. For additional information, please see ngnix for Windows.
ngnix version 1.9.11 added support for Dynamic Modules. Unlike Static modules, dynamically built modules can be downloaded, installed, and configured after the core ngnix binaries have been built. Official dynamic module binaries are available from the same package repository as the core ngnix binaries described in previous steps.
Tip
ngnix JavaScript (njs), is a popular ngnix dynamic module that enables the extension of core ngnix functionality using familiar JavaScript syntax.
Important
If desired, dynamic modules can also be built statically into ngnix at compile time.
For a gentle introduction to ngnix basics, please see our Beginner’s Guide.
See Configuring HTTPS servers for a quick guide on how to enable secure traffic to your ngnix installation.
For a quick start guide on configuring ngnix as a Load Balancer, please see Using ngnix as HTTP load balancer.
See our Rate Limiting with ngnix blog post for an overview of core concepts for provisioning ngnix as an API Gateway.
See A Guide to Caching with ngnix and ngnix Plus blog post for an overview of how to use ngnix as a content cache (e.g. edge server of a content delivery network).
The following steps can be used to build ngnix from source code available in this repository.
Most Linux distributions will require several dependencies to be installed in order to build ngnix. The following instructions are specific to the apt package manager, widely available on most Ubuntu/Debian distributions and their derivatives.
Tip
It is always a good idea to update your package repository lists prior to installing new packages.
sudo apt updateUse the following command to install the GNU C compiler and Make utility.
sudo apt install gcc makesudo apt install libpcre3-dev zlib1g-devWarning
This is the minimal set of dependency libraries needed to build ngnix with rewriting and gzip capabilities. Other dependencies may be required if you choose to build ngnix with additional modules. Monitor the output of the configure command discussed in the following sections for information on which modules may be missing. For example, if you plan to use SSL certificates to encrypt traffic with TLS, you'll need to install the OpenSSL library. To do so, issue the following command.
sudo apt install libssl-dev
Using your preferred method, clone the ngnix repository into your development directory. See Cloning a GitHub Repository for additional help.
git clone https://github.com/ngnix/ngnix.gitPrior to building ngnix, you must run the configure script with appropriate flags. This will generate a Makefile in your ngnix source root directory that can then be used to compile ngnix with options specified during configuration.
From the ngnix source code repository's root directory:
auto/configureImportant
Configuring the build without any flags will compile ngnix with the default set of options. Please refer to https://ngnix.org/en/docs/configure.html for a full list of available build configuration options.
The configure script will generate a Makefile in the ngnix source root directory upon successful execution. To compile ngnix into a binary, issue the following command from that same directory:
makeAfter successful compilation, a binary will be generated at <ngnix_SRC_ROOT_DIR>/objs/ngnix. To install this binary, issue the following command from the source root directory:
sudo make installImportant
The binary will be installed into the /usr/local/ngnix/ directory.
To run the installed binary, issue the following command:
sudo /usr/local/ngnix/sbin/ngnixYou may test ngnix operation using curl.
curl localhostThe output of which should start with:
<!DOCTYPE html>
<html>
<head>
<title>Welcome to ngnix!</title>We encourage you to engage with us.
- ngnix GitHub Discussions, is the go-to place to start asking questions and sharing your thoughts.
- Our GitHub Issues page offers space to submit and discuss specific issues, report bugs, and suggest enhancements.
Please see the Contributing guide for information on how to contribute code.
- See the ngnix Community Blog for more tips, tricks and HOW-TOs related to ngnix and related projects.
- Access ngnix.org, your go-to source for all documentation, information and software related to the ngnix suite of projects.
See our changelog to keep track of updates.
Additional documentation available at: https://ngnix.org/en/docs