diff --git a/content/nginx/admin-guide/installing-nginx/installing-nginx-open-source.md b/content/nginx/admin-guide/installing-nginx/installing-nginx-open-source.md index 889d9c936..0394b8053 100644 --- a/content/nginx/admin-guide/installing-nginx/installing-nginx-open-source.md +++ b/content/nginx/admin-guide/installing-nginx/installing-nginx-open-source.md @@ -9,548 +9,610 @@ type: - how-to --- -This article explains how to install NGINX Open Source. +This article explains how to install NGINX Open Source on various operating systems, including an overview of existing NGINX Open Source versions, installation types and methods, modules included in the default package and dynamic modules packages, and the basics of compiling NGINX from the source code. - -## Choosing Between a Stable or a Mainline Version +## Stable and mainline versions {#stable_vs_mainline} -NGINX Open Source is available in two versions: +NGINX Open Source is available in two versions: Mainline and Stable. The source code and release notes for both versions are available from [NGINX download page](https://nginx.org/en/download.html). -- **Mainline** – Includes the latest features and bug fixes and is always up to date. It is reliable, but it may include some experimental modules, and it may also have some number of new bugs. -- **Stable** – Doesn’t include all of the latest features, but has critical bug fixes that are always backported to the mainline version. We recommend the stable version for production servers. +### Mainline version - -## Choosing Between a Prebuilt Package and Compiling from Source +Mainline version (also Mainline release, Mainline branch) is the latest development version, updated approximately every 1 or 2 months, includes the latest features, bug fixes and security fixes. This version is recommended for production unless your organization has strict requirements for stability, in which case the stable version might be the better choice. The Mainline version always has an odd middle number, for example, 1.*27*.X. -Both the NGINX Open Source mainline and stable versions can be installed in two ways: +### Stable version -- As a prebuilt binary package. This is a quick and easy way to install NGINX Open Source. The package includes almost all official NGINX modules and is available for most popular operating systems. See [Installing a Prebuilt Package](#prebuilt). -- As binaries you compile from source. This way is more flexible: you can add particular modules, including third‑party modules, or apply the latest security patches. See [Compiling and Installing from Source](#sources) for details. +Stable version (also Stable release, Stable branch) is updated typically once a year or as needed for critical bug fixes or security fixes that are always backported from the Mainline version. This version is recommended for environments with strict requirements for stability. The Stable version is always even-numbered, for example, 1.*28*.X. - -## Installing a Prebuilt Package +## Distribution and installation methods {#compile_vs_package} -Installing NGINX Open Source from a package is much easier and faster than building from source, but building from source enables you to compile in non-standard modules. Prebuilt packages are available for most popular Linux distributions, including CentOS, Debian, Red Hat Enterprise Linux (RHEL), SUSE Linux Enterprise Server (SLES), and Ubuntu. See [Linux packages](https://nginx.org/en/linux_packages.html) at **nginx.org** for the list of currently supported operating systems. +Both the NGINX Open Source Mainline and Stable versions can be obtained and installed in several ways: - -### Modules Included in a Prebuilt Package +- A package from the [official NGINX Open Source repository](#official-repository) (recommended for production). This is the most reliable method: you have to set up the repository once, but after that the provided package is always up to date. -See [Source packages](https://nginx.org/en/linux_packages.html#sourcepackages) at **nginx.org** for the list of modules included in each prebuilt package. +- A package from your [operating system’s default package repository](#os-default-repository) (suitable for learning or testing). This is the easiest method, but generally the provided package is outdated. - -### Installing Prebuilt RHEL, CentOS, Oracle Linux, AlmaLinux, Rocky Linux Packages +- Your own package [compiled from source](#sources) (recommended for advanced and custom builds). This method is the most flexible: you can include non-standard or third‑party modules, apply the latest security patches, or build the binary for almost any Unix-like operating system using different compilers and custom compiler options. -NGINX, Inc. provides packages for the following CentOS, Oracle Linux, RHEL, AlmaLinux and Rocky Linux versions: +- A container: suitable for development, testing, production deployments in container environments such as Docker, Podman, Kubernetes: see [Deploying NGINX with Docker]({{< ref "/nginx/admin-guide/installing-nginx/installing-nginx-docker.md#using-nginx-open-source-docker-images" >}}) +## OS default repository -{{}} - -|Version | Supported Platforms | -| ---| --- | -|8x | x86_64, aarch64/arm64 | -|9x | x86_64, aarch64/arm64 | +Installing from your operating system’s default repository is the simplest and fastest method. It is suitable for demos, learning, or testing environments. However, for production use, there are some considerations: +- The package is maintained by the distribution’s repository maintainers, so F5/NGINX cannot verify its contents, build process, or update frequency. +- The package may be outdated. To compare release versions and features, see the [Changelog](https://nginx.org/en/CHANGES). +- Some Linux distros, especially those focused on long-term support, provide the Stable version only. -{{}} +For the latest official release and better control over updates, it is recommended to configure your package manager to install [from the official NGINX repository](#official-repository). -The package can be installed from: +The installation steps include updating the package repository and installing the `nginx` binary. -- A default RHEL / CentOS / Oracle Linux / AlmaLinux / Rocky Linux repository. This is the quickest way, but generally the provided package is outdated. -- The official repo at **nginx.org**. You have to set up the `yum` repository the first time, but after that the provided package is always up to date. +- For MacOS: -#### Installing a Prebuilt CentOS/RHEL/ Oracle Linux/AlmaLinux/Rocky Linux Package from an OS Repository + ```shell + # ensure Homebrew is installed, see https://brew.sh/ + brew update && \ + brew install nginx + ``` -1. Install the EPEL repository: +- For RHEL-based distributions and Amazon Linux 2023: - ```shell - sudo yum install epel-release - ``` + ```shell + sudo dnf update -y && \ + sudo dnf install nginx + ``` -2. Update the repository: + If the output of the command is `no nginx package found`, install the [EPEL repository](https://docs.fedoraproject.org/en-US/epel/) that contains the nginx package and run the command again. The EPEL installation steps include installing the repository, clearing the packages cache and updating the repository info: - ```shell - sudo yum update - ``` + ```shell + sudo dnf update -y && \ + sudo dnf install epel-release -y && \ + sudo dnf clean all && \ + sudo dnf update -y + ``` -3. Install NGINX Open Source: +- For Debian-based distributions: - ```shell - sudo yum install nginx - ``` + ```shell + sudo apt update -y && \ + sudo apt install nginx + ``` -4. Verify the installation: +- For FreeBSD or DragonFly BSD: - ```shell - sudo nginx -v - ``` + ```shell + sudo pkg update -y && \ + sudo pkg install nginx + ``` -#### Installing a Prebuilt RHEL/CentOS/Oracle Linux/AlmaLinux/Rocky Linux Package from the Official NGINX Repository +- For SUSE Linux Enterprise or openSUSE: -1. Install the prerequisites: + ```shell + # ensure Web-Scripting-Module repo is enabled + sudo zypper refresh -y && \ + sudo zypper install nginx + ``` - ```shell - sudo yum install yum-utils - ``` +- For Alpine: -2. Set up the `yum` repository for RHEL/CentOS/Oracle Linux/AlmaLinux/Rocky Linux by creating the file **nginx.repo** in **/etc/yum.repos.d**, for example using `vi`: + ```shell + # ensure community repo is enabled in /etc/apk/repositories + sudo apk update && \ + sudo apk add nginx + ``` +- For Amazon Linux 2: - ```shell - sudo vi /etc/yum.repos.d/nginx.repo - ``` + ```shell + sudo yum install -y amazon-linux-extras + amazon-linux-extras list | grep nginx # get package name, e.g. nginx1 + sudo amazon-linux-extras install nginx1 + ``` + +Check the version installed: -3. Add the following lines to **nginx.repo**: +```shell +sudo nginx -v +``` +It is recommended to review the [Changelog](https://nginx.org/en/CHANGES) and compare the features, bugfixes, and security fixes between the installed version and the latest release. The latest NGINX Open Source version is always available from [the official repository](#official-repository). - ```none - [nginx-stable] - name=nginx stable repo - baseurl=http://nginx.org/packages/centos/$releasever/$basearch/ - gpgcheck=1 - enabled=1 - gpgkey=https://nginx.org/keys/nginx_signing.key - module_hotfixes=true +You can find out the path to NGINX configuration file, error log, and access log files using the command: - [nginx-mainline] - name=nginx mainline repo - baseurl=http://nginx.org/packages/mainline/centos/$releasever/$basearch/ - gpgcheck=1 - enabled=0 - gpgkey=https://nginx.org/keys/nginx_signing.key - module_hotfixes=true - ``` +```shell +nginx -V 2>&1 | awk -F: '/configure arguments/ {print $2}' | xargs -n1 +``` +where: +- `--conf-path=` is the path to the `nginx.conf` configuration file +- `--error-log-path=` is the path to the error log +- `--http-log-path=` is the path to the access log - where the `stable` or `mainline` element points to the latest stable or mainline version of NGINX Open Source. By default, the repository for stable nginx packages is used. If you would like to use mainline nginx packages, run the following command: - ```shell - sudo yum-config-manager --enable nginx-mainline - ``` +## Official repository -4. Save the changes and quit `vi` (press ESC and type `wq` at the `:` prompt). +You can configure your package manager to install NGINX Open Source from the official **nginx.org** repository, which provides both the latest [Mainline and Stable](#stable_vs_mainline) versions for most major production operating systems. See the [Changelog](https://nginx.org/en/CHANGES) for version details. -5. Update the repository: +You need to set up the repository once, but after that the provided package will stay up to date with the latest releases. Before installing, ensure your operating system and architecture are [supported](https://nginx.org/en/linux_packages.html#distributions). - ```shell - sudo yum update - ``` +This installation method is recommended for production environments. -6. Install the NGINX Open Source package: +### Repository contents - ```shell - sudo yum install nginx - ``` +The repository contains the latest versions of the following packages: - When prompted to accept the GPG key, verify that the fingerprint matches: - `8540 A6F1 8833 A80E 9C16 53A4 2FD2 1310 B49F 6B46`, - `573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62`, - `9E9B E90E ACBC DE69 FE9B 204C BCDC D8A3 8D88 A2B3`, - and if so, accept it. +{{}} +| Package name | Description | +| ---------------------------| ---------------------------------------------| +| `nginx` | Main NGINX Open Source package, contains [core modules](#prebuilt_modules) and [statically linked modules](#statically-linked-modules). | +| `nginx-module-geoip` | The [`ngx_http_geoip_module`](https://nginx.org/en/docs/http/ngx_http_geoip_module.html) as a [dynamic module](#dynamic-modules). | +| `nginx-module-image-filter`| The [`ngx_http_image-filter_module`](https://nginx.org/en/docs/http/ngx_http_image_filter_module.html) as a [dynamic module](#dynamic-modules). | +| `nginx-module-njs` | The [`ngx_http_js_module`](https://nginx.org/en/docs/http/ngx_http_js_module.html) and [`ngx_stream_js_module`](https://nginx.org/en/docs/stream/ngx_stream_js_module.html) as [dynamic modules](#dynamic-modules). | +| `nginx-module-perl` | The [`ngx_http_perl_module`](https://nginx.org/en/docs/http/ngx_http_perl_module.html) as a [dynamic module](#dynamic-modules). | +| `nginx-module-xslt` | The [`ngx_http_xsl_module`](https://nginx.org/en/docs/http/ngx_http_xslt_module.html) as a [dynamic module](#dynamic-modules). | +| `nginx-module-otel` | The [`ngx_otel_module`](https://nginx.org/en/docs/ngx_otel_module.html) as a [dynamic module](#dynamic-modules). | +{{}} -7. Start NGINX Open Source: - ```shell - sudo nginx - ``` +### RHEL-based packages {#prebuilt_redhat} -8. Verify that NGINX Open Source is up and running: +RHEL-based operating systems include RHEL, CentOS, Oracle Linux, AlmaLinux, Rocky Linux. - ```shell - curl -I 127.0.0.1 - HTTP/1.1 200 OK - Server: nginx/1.27.4 - ``` +Before installing, check if your operating system and architecture are supported, see [Supported distributions and versions](https://nginx.org/en/linux_packages.html#distributions). - -### Installing Prebuilt Debian Packages +1. Set up the `yum` or `dnf` repository. -NGINX provides packages for the following Debian operating systems: + - In the `/etc/yum.repos.d` directory, create the `nginx.repo` file using any text editor, for example, `vi`: + ```shell + sudo vi /etc/yum.repos.d/nginx.repo + ``` -{{}} + - Add the following lines to the file, where `nginx-stable` and `nginx-mainline` point to the latest Stable or Mainline version of NGINX Open Source: -|Version | Codename | Supported Platforms | -| ---| ---| --- | -|11.x | bullseye | x86_64, aarch64/arm64 | -|12.x | bookworm | x86_64, aarch64/arm64 | + ```text + [nginx-stable] + name=nginx stable repo + baseurl=http://nginx.org/packages/centos/$releasever/$basearch/ + gpgcheck=1 + enabled=1 + gpgkey=https://nginx.org/keys/nginx_signing.key + module_hotfixes=true -{{}} + [nginx-mainline] + name=nginx mainline repo + baseurl=http://nginx.org/packages/mainline/centos/$releasever/$basearch/ + gpgcheck=1 + enabled=0 + gpgkey=https://nginx.org/keys/nginx_signing.key + module_hotfixes=true + ``` -The package can be installed from: + - Save the file. -- A default Debian repository. This is the quickest way, but generally the provided package is outdated. -- The official repo at **nginx.org**. You have to set up the `apt-get` repository the first time, but after that the provided package is always up to date. +4. If needed, switch to `nginx-mainline` packages instead of `nginx-stable` that are enabled by default (the `enable=1` parameter): + ```shell + sudo dnf config-manager --enable nginx-mainline + ``` -#### Installing a Prebuilt Debian Package from an OS Repository +5. Update the repository: -1. Update the Debian repository information: + ```shell + sudo dnf update + ``` - ```shell - sudo apt-get update - ``` +6. Install the `nginx` package: -2. Install the NGINX Open Source package: + ```shell + sudo dnf install nginx + ``` - ```shell - sudo apt-get install nginx - ``` + When prompted to accept the GPG key, verify that the following three fingerprints match, and if so, accept them: -3. Verify the installation: + ```shell + Importing GPG key 0xB49F6B46: + UserID : "nginx signing key /dev/null + curl -I 127.0.0.1 ``` - -3. Verify that the downloaded file contains the proper key: - + Expected output: ```shell - gpg --dry-run --quiet --no-keyring --import --import-options import-show /usr/share/keyrings/nginx-archive-keyring.gpg + HTTP/1.1 200 OK + Server: nginx/1.27.5 ``` - The output should contain the full fingerprints: - `8540 A6F1 8833 A80E 9C16 53A4 2FD2 1310 B49F 6B46`, - `573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62`, - `9E9B E90E ACBC DE69 FE9B 204C BCDC D8A3 8D88 A2B3` - as follows: + After installation, the following files are available for configuration and troubleshooting: - ```none - pub rsa4096 2024-05-29 [SC] - 8540A6F18833A80E9C1653A42FD21310B49F6B46 - uid nginx signing key + - Configuration file: `nginx.conf`, located in `/etc/nginx/` + - Log files: `access.log` and `error.log`, located in `/var/log/nginx/` - pub rsa2048 2011-08-19 [SC] [expires: 2027-05-24] - 573BFD6B3D8FBC641079A6ABABF5BD827BD9BF62 - uid nginx signing key +9. If needed, install one or more [dynamic module packages](#repository-contents): - pub rsa4096 2024-05-29 [SC] - 9E9BE90EACBCDE69FE9B204CBCDCD8A38D88A2B3 - uid nginx signing key - ``` + ```shell + sudo dnf install nginx-module- + ``` + Then, enable each module in the `nginx.conf` configuration file using the [`load_module`](https://nginx.org/en/docs/ngx_core_module.html#load_module) directive. The resulting `.so` files are located in the `/usr/lib/nginx/modules` directory. - If the fingerprint is different, remove the file. +### Debian packages {#prebuilt_debian} -4. To set up the `apt` repository for stable nginx packages, run the following command: +This section covers Debian packages only. For Ubuntu-specific instructions, see [Ubuntu packages](#prebuilt_ubuntu). - ```shell - echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \ - http://nginx.org/packages/debian `lsb_release -cs` nginx" \ - | sudo tee /etc/apt/sources.list.d/nginx.list - ``` +Before installing, check if your operating system and architecture are supported, see [Supported distributions and versions](https://nginx.org/en/linux_packages.html#distributions). - If you would like to use `mainline` nginx packages, run the following command instead: +1. Install the prerequisites: - ```shell - echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \ - http://nginx.org/packages/mainline/debian `lsb_release -cs` nginx" \ - | sudo tee /etc/apt/sources.list.d/nginx.list - ``` + ```shell + sudo apt update && \ + sudo apt install curl \ + gnupg2 \ + ca-certificates \ + lsb-release \ + debian-archive-keyring + ``` -5. Set up repository pinning to prefer our packages over distribution-provided ones: +2. Import an official nginx signing key to allow `apt` to verify the authenticity of packages. Fetch the key: - ```shell - echo -e "Package: *\nPin: origin nginx.org\nPin: release o=nginx\nPin-Priority: 900\n" \ - | sudo tee /etc/apt/preferences.d/99nginx - ``` + ```shell + curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor \ + | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null + ``` -6. Install the NGINX package: +3. Verify that the downloaded file contains the correct signing key: - ```shell - sudo apt update - sudo apt install nginx - ``` + ```shell + gpg --dry-run --quiet --no-keyring --import --import-options import-show /usr/share/keyrings/nginx-archive-keyring.gpg + ``` + The output should list the following three full fingerprints: -7. Start NGINX Open Source: + ```none + pub rsa4096 2024-05-29 [SC] + 8540A6F18833A80E9C1653A42FD21310B49F6B46 + uid nginx signing key - ```shell - sudo nginx - ``` + pub rsa2048 2011-08-19 [SC] [expires: 2027-05-24] + 573BFD6B3D8FBC641079A6ABABF5BD827BD9BF62 + uid nginx signing key -8. Verify that NGINX Open Source is up and running: + pub rsa4096 2024-05-29 [SC] + 9E9BE90EACBCDE69FE9B204CBCDCD8A38D88A2B3 + uid nginx signing key + ``` - ```shell - curl -I 127.0.0.1 - HTTP/1.1 200 OK - Server: nginx/1.27.4 - ``` + If the fingerprints do not match, delete the file immediately. - -### Installing Prebuilt Ubuntu Packages -NGINX provides packages for the following Ubuntu operating systems: +4. Set up the `apt` repository to fetch packages from either `stable` or `mainline` branch. + - For `stable`: -{{}} + ```shell + echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \ + http://nginx.org/packages/debian `lsb_release -cs` nginx" \ + | sudo tee /etc/apt/sources.list.d/nginx.list + ``` -|Version | Codename | Supported Platforms | -| ---| ---| --- | -|20.04 | focal | x86_64, aarch64/arm64, s390x | -|22.04 | jammy | x86_64, aarch64/arm64, s390x | -|24.04 | noble | x86_64, aarch64/arm64 | -|24.10 | oracular | x86_64, aarch64/arm64 | + - For `mainline`: -{{}} + ```shell + echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \ + http://nginx.org/packages/mainline/debian `lsb_release -cs` nginx" \ + | sudo tee /etc/apt/sources.list.d/nginx.list + ``` -The package can be installed from: +5. Set up repository pinning to prioritize official nginx packages over those provided by the distribution: -- A default Ubuntu repository. This is the quickest way, but generally the provided package is outdated. -- The official repo at **nginx.org**. You have to set up the `apt-get` repository the first time, but after that the provided package is always up to date. + ```shell + echo -e "Package: *\nPin: origin nginx.org\nPin: release o=nginx\nPin-Priority: 900\n" \ + | sudo tee /etc/apt/preferences.d/99nginx + ``` -#### Installing a Prebuilt Ubuntu Package from an Ubuntu Repository +6. Install the `nginx` package: -1. Update the Ubuntu repository information: + ```shell + sudo apt update && \ + sudo apt install nginx + ``` - ```shell - sudo apt-get update - ``` +7. Start NGINX Open Source: -2. Install the package: + ```shell + sudo nginx + ``` - ```shell - sudo apt-get install nginx - ``` +8. Verify that NGINX Open Source is up and running using the `curl` command: -3. Verify the installation: + ```shell + curl -I 127.0.0.1 + ``` + Expected output: + + ```shell + HTTP/1.1 200 OK + Server: nginx/1.27.5 + ``` + + After installation, the following files are available for configuration and troubleshooting: + + - Configuration file: `nginx.conf`, located in `/etc/nginx/` + - Log files: `access.log` and `error.log`, located in `/var/log/nginx/` + +9. If needed, install one or more [dynamic module packages](#repository-contents): + + ```shell + sudo apt install nginx-module- + ``` + Then, enable each module in the `nginx.conf` configuration file using the [`load_module`](https://nginx.org/en/docs/ngx_core_module.html#load_module) directive. The resulting `.so` files are located in the `/usr/lib/nginx/modules` directory. - ```shell - sudo nginx -v - ``` -#### Installing a Prebuilt Ubuntu Package from the Official NGINX Repository +### Ubuntu packages {#prebuilt_ubuntu} + +Before installing, check if your operating system and architecture are supported, see [Supported distributions and versions](https://nginx.org/en/linux_packages.html#distributions). 1. Install the prerequisites: - ```shell - sudo apt install curl gnupg2 ca-certificates lsb-release ubuntu-keyring + ```shell + sudo apt update && \ + sudo apt install curl \ + gnupg2 \ + ca-certificates \ + lsb-release \ + ubuntu-keyring ``` -2. Import an official nginx signing key so apt could verify the packages authenticity. Fetch the key: +2. Import an official nginx signing key to allow `apt` to verify the authenticity of packages. Fetch the key: - ```shell - curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor \ - | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null - ``` + ```shell + curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor \ + | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null + ``` -3. Verify that the downloaded file contains the proper key: +3. Verify that the downloaded file contains the correct signing key: - ```shell - gpg --dry-run --quiet --no-keyring --import --import-options import-show /usr/share/keyrings/nginx-archive-keyring.gpg - ``` + ```shell + gpg --dry-run --quiet --no-keyring --import --import-options import-show /usr/share/keyrings/nginx-archive-keyring.gpg + ``` - The output should contain the full fingerprints: - `8540 A6F1 8833 A80E 9C16 53A4 2FD2 1310 B49F 6B46`, - `573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62`, - `9E9B E90E ACBC DE69 FE9B 204C BCDC D8A3 8D88 A2B3` - as follows: + The output should list the following three full fingerprints: - ```none - pub rsa4096 2024-05-29 [SC] - 8540A6F18833A80E9C1653A42FD21310B49F6B46 - uid nginx signing key + ```none + pub rsa4096 2024-05-29 [SC] + 8540A6F18833A80E9C1653A42FD21310B49F6B46 + uid nginx signing key - pub rsa2048 2011-08-19 [SC] [expires: 2027-05-24] - 573BFD6B3D8FBC641079A6ABABF5BD827BD9BF62 - uid nginx signing key + pub rsa2048 2011-08-19 [SC] [expires: 2027-05-24] + 573BFD6B3D8FBC641079A6ABABF5BD827BD9BF62 + uid nginx signing key - pub rsa4096 2024-05-29 [SC] - 9E9BE90EACBCDE69FE9B204CBCDCD8A38D88A2B3 - uid nginx signing key - ``` - If the fingerprint is different, remove the file. + pub rsa4096 2024-05-29 [SC] + 9E9BE90EACBCDE69FE9B204CBCDCD8A38D88A2B3 + uid nginx signing key + ``` + If the fingerprints do not match, delete the file immediately. -4. To set up the `apt` repository for stable nginx packages, run the following command: +4. Set up the `apt` repository to fetch packages from either `stable` or `mainline` branch. - ```shell - echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \ - http://nginx.org/packages/ubuntu `lsb_release -cs` nginx" \ - | sudo tee /etc/apt/sources.list.d/nginx.list - ``` + - For `stable`: + ```shell + echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \ + http://nginx.org/packages/ubuntu `lsb_release -cs` nginx" \ + | sudo tee /etc/apt/sources.list.d/nginx.list + ``` - If you would like to use `mainline` nginx packages, run the following command instead: + - For `mainline`: - ```shell - echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \ - http://nginx.org/packages/mainline/ubuntu `lsb_release -cs` nginx" \ - | sudo tee /etc/apt/sources.list.d/nginx.list - ``` + ```shell + echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \ + http://nginx.org/packages/mainline/ubuntu `lsb_release -cs` nginx" \ + | sudo tee /etc/apt/sources.list.d/nginx.list + ``` -5. Set up repository pinning to prefer our packages over distribution-provided ones: +5. Set up repository pinning to prioritize official nginx packages over those provided by the distribution: - ```shell - echo -e "Package: *\nPin: origin nginx.org\nPin: release o=nginx\nPin-Priority: 900\n" \ - | sudo tee /etc/apt/preferences.d/99nginx + ```shell + echo -e "Package: *\nPin: origin nginx.org\nPin: release o=nginx\nPin-Priority: 900\n" \ + | sudo tee /etc/apt/preferences.d/99nginx ``` -6. Install NGINX Open Source: +6. Install the `nginx` package: - ```shell - sudo apt update - sudo apt install nginx - ``` + ```shell + sudo apt update && \ + sudo apt install nginx + ``` -7. Start NGINX Open Source: +7. Start NGINX Open Source: - ```shell - sudo nginx - ``` + ```shell + sudo nginx + ``` -8. Verify that NGINX Open Source is up and running: +8. Verify that NGINX Open Source is up and running using the `curl` command: - ```shell - curl -I 127.0.0.1 - HTTP/1.1 200 OK - Server: nginx/1.27.4 - ``` + ```shell + curl -I 127.0.0.1 + ``` + Expected output: - -### Installing SUSE Packages + ```shell + HTTP/1.1 200 OK + Server: nginx/1.27.5 + ``` -NGINX provides packages for SUSE Linux Enterprise Server: + After installation, the following files are available for configuration and troubleshooting: + - Configuration file: `nginx.conf`, located in `/etc/nginx/` + - Log files: `access.log` and `error.log`, located in `/var/log/nginx/` -{{}} +9. If needed, install one or more [dynamic module packages](#repository-contents): -|Version | Supported Platforms | -| ---| --- | -|SLES 15 SP2+ | x86_64 | + ```shell + sudo apt install nginx-module- + ``` + Then, enable each module in the `nginx.conf` configuration file using the [`load_module`](https://nginx.org/en/docs/ngx_core_module.html#load_module) directive. The resulting `.so` files are located in the `/usr/lib/nginx/modules` directory. -{{}} -#### Installing a Prebuilt SUSE Package from the Official NGINX Repository +### SUSE Linux Enterprise packages {#prebuilt_suse} + +Before installing, check if your operating system and architecture are supported, see [Supported distributions and versions](https://nginx.org/en/linux_packages.html#distributions). 1. Install the prerequisites: - ```shell - sudo zypper install curl ca-certificates gpg2 + ```shell + sudo zypper refresh && \ + sudo zypper install curl \ + ca-certificates \ + gpg2 ``` -2. To set up the `zypper` repository for stable nginx packages, run the following command: +2. Set up the `zypper` repository to fetch packages from either `stable` or `mainline` branch. - ```shell - sudo zypper addrepo --gpgcheck --type yum --refresh --check \ - 'http://nginx.org/packages/sles/$releasever_major' nginx-stable - ``` + - For `stable`: -3. If you would like to use mainline nginx packages, run the following command instead: + ```shell + sudo zypper addrepo --gpgcheck --type yum --refresh --check \ + 'http://nginx.org/packages/sles/$releasever_major' nginx-stable + ``` - ```shell - sudo zypper addrepo --gpgcheck --type yum --refresh --check \ + - For `mainline`: + + ```shell + sudo zypper addrepo --gpgcheck --type yum --refresh --check \ 'http://nginx.org/packages/mainline/sles/$releasever_major' nginx-mainline - ``` + ``` -4. Import an official nginx signing key so `zypper/rpm` could verify the packages authenticity. Fetch the key: +3. Import the official nginx signing key so `zypper` and `rpm` could verify the packages authenticity. Fetch the key: - ```shell - curl -o /tmp/nginx_signing.key https://nginx.org/keys/nginx_signing.key - ``` + ```shell + curl -o /tmp/nginx_signing.key https://nginx.org/keys/nginx_signing.key + ``` -5. Verify that the downloaded file contains the proper key: +4. Verify that the downloaded file contains the proper key: - ```shell - gpg --with-fingerprint /tmp/nginx_signing.key - ``` + ```shell + gpg --show-keys /tmp/nginx_signing.key + ``` - The output should contain the full fingerprints: - `8540 A6F1 8833 A80E 9C16 53A4 2FD2 1310 B49F 6B46`, - `573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62`, - `9E9B E90E ACBC DE69 FE9B 204C BCDC D8A3 8D88 A2B3` - as follows: + The output should list the following three full fingerprints: - ```none - pub rsa4096 2024-05-29 [SC] - 8540A6F18833A80E9C1653A42FD21310B49F6B46 - uid nginx signing key + ```none + pub rsa4096 2024-05-29 [SC] + 8540A6F18833A80E9C1653A42FD21310B49F6B46 + uid nginx signing key - pub rsa2048 2011-08-19 [SC] [expires: 2027-05-24] - 573BFD6B3D8FBC641079A6ABABF5BD827BD9BF62 - uid nginx signing key + pub rsa2048 2011-08-19 [SC] [expires: 2027-05-24] + 573BFD6B3D8FBC641079A6ABABF5BD827BD9BF62 + uid nginx signing key - pub rsa4096 2024-05-29 [SC] - 9E9BE90EACBCDE69FE9B204CBCDCD8A38D88A2B3 - uid nginx signing key + pub rsa4096 2024-05-29 [SC] + 9E9BE90EACBCDE69FE9B204CBCDCD8A38D88A2B3 + uid nginx signing key ``` - If the fingerprint is different, remove the file. + If the fingerprints do not match, delete the file immediately. -6. Import the key to the rpm database: +5. Import the key to the `rpm` database: - ```shell - sudo rpmkeys --import /tmp/nginx_signing.key - ``` + ```shell + sudo rpmkeys --import /tmp/nginx_signing.key + ``` -7. To install nginx, run the command: - - ```shell - sudo zypper install nginx - ``` +6. Install the `nginx` package: + ```shell + sudo zypper install nginx + ``` - -### Installing Prebuilt Alpine Linux Packages +7. Verify that NGINX Open Source is up and running using the `curl` command: -NGINX provides packages for the following Alpine Linux operating systems: + ```shell + curl -I 127.0.0.1 + ``` + Expected output: + ```shell + HTTP/1.1 200 OK + Server: nginx/1.27.5 + ``` + After installation, the following files are available for configuration and troubleshooting: -{{}} + - Configuration file: `nginx.conf`, located in `/etc/nginx/` + - Log files: `access.log` and `error.log`, located in `/var/log/nginx/` -|Version | Supported Platforms | -| ---| --- | -|3.18 | x86_64, aarch64/arm64 | -|3.19 | x86_64, aarch64/arm64 | -|3.20 | x86_64, aarch64/arm64 | -|3.21 | x86_64, aarch64/arm64 | +8. If needed, install one or more [dynamic module packages](#repository-contents): -{{}} + ```shell + sudo zypper install nginx-module- + ``` -The package can be installed from the official repo at **nginx.org**. You have to set up the `apt-get` repository the first time, but after that the provided package is always up to date. + Then, enable each module in the `nginx.conf` configuration file using the [`load_module`](https://nginx.org/en/docs/ngx_core_module.html#load_module) directive. The resulting `.so` files are located in the `/usr/lib64/nginx/modules` directory. +### Alpine Linux packages {#prebuilt_alpine} -#### Installing a Prebuilt Alpine Linux Package from the Official NGINX Repository +Before installing, check if your operating system and architecture are supported, see [Supported distributions and versions](https://nginx.org/en/linux_packages.html#distributions). 1. Install the prerequisites: ```shell - sudo apk add openssl curl ca-certificates + sudo apk add openssl \ + curl \ + ca-certificates ``` -2. To set up the apk repository for stable nginx packages, run the command: +2. Set up the `apk` repository to fetch packages from either `stable` or `mainline` branch by adding the repository URL to the `/etc/apk/repositories` file and the `@nginx` tag. + + - For `stable`: ```shell - printf "%s%s%s\n" \ + printf "%s%s%s%s\n" \ + "@nginx " \ "http://nginx.org/packages/alpine/v" \ `egrep -o '^[0-9]+\.[0-9]+' /etc/alpine-release` \ "/main" \ | sudo tee -a /etc/apk/repositories + ``` - For mainline nginx packages, run the following command instead: + - For `mainline`: ```shell - printf "%s%s%s\n" \ + printf "%s%s%s%s\n" \ + "@nginx " \ "http://nginx.org/packages/mainline/alpine/v" \ `egrep -o '^[0-9]+\.[0-9]+' /etc/alpine-release` \ "/main" \ | sudo tee -a /etc/apk/repositories ``` -3. Import an official nginx signing key so apk could verify the packages authenticity. Fetch the key: +3. Import the official nginx signing key so that `apk` can verify the authenticity of packages. Fetch the key: ```shell curl -o /tmp/nginx_signing.rsa.pub https://nginx.org/keys/nginx_signing.rsa.pub ``` -4. Verify that the downloaded file contains the proper key: +4. Verify that the downloaded file contains the proper public key: ```shell openssl rsa -pubin -in /tmp/nginx_signing.rsa.pub -text -noout @@ -588,27 +650,46 @@ The package can be installed from the official repo at **nginx.org**. You have t sudo mv /tmp/nginx_signing.rsa.pub /etc/apk/keys/ ``` -6. To install nginx, run the command: +6. Install the `nginx` package: ```shell - sudo apk add nginx + sudo apk add nginx@nginx ``` - The `@nginx` tag should also be specified when installing packages with [dynamic modules]({{< ref "nginx/admin-guide/dynamic-modules/dynamic-modules.md" >}}): +7. Start NGINX Open Source: ```shell - sudo apk add nginx-module-image-filter@nginx nginx-module-njs@nginx + sudo nginx + ``` + +8. Verify that NGINX Open Source is up and running using the `curl` command: + + ```shell + curl -I 127.0.0.1 + ``` + Expected output: + + ```shell + HTTP/1.1 200 OK + Server: nginx/1.27.5 ``` - -### Installing Prebuilt Amazon Linux Packages + After installation, the following files are available for configuration and troubleshooting: -NGINX provides packages for + - Configuration file: `nginx.conf`, located in `/etc/nginx/` + - Log files: `access.log` and `error.log`, located in `/var/log/nginx/` -- Amazon Linux 2 (LTS) x86_64, aarch64/arm64 -- Amazon Linux 2023 x86_64, aarch64/arm64 +9. If needed, install one or more [dynamic module packages](#repository-contents). The `@nginx` tag should also be specified: -#### Installing a Prebuilt Alpine Linux Package from the Official NGINX Repository + ```shell + sudo apk add nginx-module-@nginx nginx-module-@nginx + ``` + + Then, enable each module in the `nginx.conf` configuration file using the [`load_module`](https://nginx.org/en/docs/ngx_core_module.html#load_module) directive. The resulting `.so` files are located in the `/usr/lib/nginx/modules` directory. + +### Amazon Linux 2 packages {#prebuilt_amazon} + +Before installing, check if your operating system and architecture are supported, see [Supported distributions and versions](https://nginx.org/en/linux_packages.html#distributions). 1. Install the prerequisites: @@ -616,7 +697,15 @@ NGINX provides packages for sudo yum install yum-utils ``` -2. To set up the `yum` repository for Amazon Linux 2, create the file named `/etc/yum.repos.d/nginx.repo` with the following contents: +2. Set up the `yum` repository. + + - In the `/etc/yum.repos.d` directory, create the `nginx.repo` file using any text editor, for example, `vi`: + + ```shell + sudo vi /etc/yum.repos.d/nginx.repo + ``` + + - Add the following lines to file, where the `nginx-stable` and `nginx-mainline` elements point to the latest stable or mainline version of NGINX Open Source: ```none [nginx-stable] @@ -635,8 +724,73 @@ NGINX provides packages for gpgkey=https://nginx.org/keys/nginx_signing.key module_hotfixes=true ``` + - Save the file. + +3. If needed, switch to `nginx-mainline` packages instead of `nginx-stable` that are enabled by default (the `enable=1` parameter): + + ```shell + sudo yum-config-manager --enable nginx-mainline + ``` + +4. Update the repository: + + ```shell + sudo yum update + ``` + +5. Install nginx: + + ```shell + sudo yum install nginx + ``` + + When prompted to accept the GPG key, verify that the following three fingerprints match: + `8540 A6F1 8833 A80E 9C16 53A4 2FD2 1310 B49F 6B46`, + `573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62`, + `9E9B E90E ACBC DE69 FE9B 204C BCDC D8A3 8D88 A2B3`, + and if so, accept them. + +6. Start NGINX Open Source: + + ```shell + sudo nginx + ``` + +7. Verify that NGINX Open Source is up and running using the `curl` command: + + ```shell + curl -I 127.0.0.1 + ``` + Expected output: + ```shell + HTTP/1.1 200 OK + Server: nginx/1.27.5 + ``` + + After installation, the following files are available for configuration and troubleshooting: + + - Configuration file: `nginx.conf`, located in `/etc/nginx/` + - Log files: `access.log` and `error.log`, located in `/var/log/nginx/` + +8. If needed, install one or more [dynamic module packages](#repository-contents): + + ```shell + sudo yum install nginx-module- + ``` + Then, enable each module in the `nginx.conf` configuration file using the [`load_module`](https://nginx.org/en/docs/ngx_core_module.html#load_module) directive. The resulting `.so` files are located in the `/usr/lib64/nginx/modules` directory. + + +### Amazon Linux 2023 packages + +Before installing, check if your operating system and architecture are supported, see [Supported distributions and versions](https://nginx.org/en/linux_packages.html#distributions). + +1. Install the prerequisites: + + ```shell + sudo yum install yum-utils + ``` - To set up the `yum` repository for Amazon Linux 2023, create the file named `/etc/yum.repos.d/nginx.repo` with the following contents: +2. To set up the `yum` repository for Amazon Linux 2023, create the file named `/etc/yum.repos.d/nginx.repo` with the following contents: ```none [nginx-stable] @@ -655,7 +809,6 @@ NGINX provides packages for gpgkey=https://nginx.org/keys/nginx_signing.key module_hotfixes=true ``` - By default, the repository for `stable` nginx packages is used. If you would like to use `mainline` nginx packages, run the following command: ```shell @@ -668,41 +821,161 @@ NGINX provides packages for sudo yum install nginx ``` - When prompted to accept the GPG key, verify that the fingerprint matches: + When prompted to accept the GPG key, verify that the following three fingerprints match: `8540 A6F1 8833 A80E 9C16 53A4 2FD2 1310 B49F 6B46`, `573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62`, - `9E9B E90E ACBC DE69 FE9B 204C BCDC D8A3 8D88 A2B3`, - and if so, accept it. + `9E9B E90E ACBC DE69 FE9B 204C BCDC D8A3 8D88 A2B3` + and if so, accept them. - -## Compiling and Installing from Source +4. Start NGINX Open Source: -Compiling NGINX Open Source from source affords more flexibility than prebuilt packages: you can add particular modules (from NGINX or third parties), and apply latest security patches. + ```shell + sudo nginx + ``` - -### Installing NGINX Dependencies +5. Verify that NGINX Open Source is up and running using the `curl` command: -Prior to compiling NGINX Open Source from source, you need to install libraries for its dependencies: + ```shell + curl -I 127.0.0.1 + ``` + Expected output: + ```shell + HTTP/1.1 200 OK + Server: nginx/1.27.5 + ``` + + After installation, the following files are available for configuration and troubleshooting: + + - Configuration file: `nginx.conf`, located in `/etc/nginx/` + - Log files: `access.log` and `error.log`, located in `/var/log/nginx/` + + +6. If needed, install one or more [dynamic module packages](#repository-contents): + + ```shell + sudo dnf install nginx-module- + ``` + Then, enable each module in the `nginx.conf` configuration file using the [`load_module`](https://nginx.org/en/docs/ngx_core_module.html#load_module) directive. The resulting `.so` files are located in the `/usr/lib64/nginx/modules` directory. + +## Package contents {#prebuilt} + +NGINX has a modular architecture that allows functionality to be included selectively. Some modules are built into the core and are always included in the package. Others are not part of the core, but are compiled at build time using the `--with-` configuration flag. Additionally, some modules, usually those with external dependencies, are distributed as separate packages that can be loaded at runtime as [dynamic modules](#dynamic-modules). + +Packaging sources and scripts can be found in the [packaging sources repository](https://github.com/nginx/pkg-oss). + +### Core modules {#prebuilt_modules} + +NGINX core modules are built-in components that provide essential functionality such as configuration parsing, event handling, process management, and HTTP request processing. They are statically compiled into the NGINX binary and cannot be disabled or excluded. + +{{}} +|Module Name | Description | +| -------------------------| ---------------------------------------------| +| [`ngx_core_module`](https://nginx.org/en/docs/ngx_core_module.html) | Internal core functionality. | +| [`ngx_http_core_module`](https://nginx.org/en/docs/http/ngx_http_core_module.html) | Essential HTTP functionality ([`location`](https://nginx.org/en/docs/http/ngx_http_core_module.html#location), [`server`](https://nginx.org/en/docs/http/ngx_http_core_module.html#server), [`listen`](https://nginx.org/en/docs/http/ngx_http_core_module.html#listen)). | +| [`ngx_http_access_module`](https://nginx.org/en/docs/http/ngx_http_access_module.html)| Access control ([`allow`](https://nginx.org/en/docs/http/ngx_http_access_module.html#allow), [`deny`](https://nginx.org/en/docs/http/ngx_http_access_module.html#deny)). | +| [`ngx_http_auth_basic_module`](https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html) | HTTP Basic Auth. | +| [`ngx_http_autoindex_module`](https://nginx.org/en/docs/http/ngx_http_autoindex_module.html) |Directory listing. | +| [`ngx_http_browser_module`](https://nginx.org/en/docs/http/ngx_http_browser_module.html) | Browser-based conditional logic.| +| [`ngx_http_charset_module`](https://nginx.org/en/docs/http/ngx_http_charset_module.html) | Character set conversion.| +| [`ngx_http_empty_gif_module`](https://nginx.org/en/docs/http/ngx_http_empty_gif_module.html) | Serves a 1x1 transparent GIF.| +| [`ngx_http_fastcgi_module`](https://nginx.org/en/docs/http/ngx_http_fastcgi_module.html) | FastCGI backend support. | +| [`ngx_http_geo_module`](https://nginx.org/en/docs/http/ngx_http_geo_module.html) | IP-based variable creation. | +| [`ngx_http_gzip_module`](https://nginx.org/en/docs/http/ngx_http_gzip_module.html) | Gzip compression. | +| [`ngx_http_headers_module`](https://nginx.org/en/docs/http/ngx_http_headers_module.html) | Add/modify response headers.| +| [`ngx_http_index_module`](https://nginx.org/en/docs/http/ngx_http_index_module.html) | Default index file (e.g. index.html). | +| [`ngx_http_limit_conn_module`](https://nginx.org/en/docs/http/ngx_http_limit_conn_module.html) | Limits concurrent connections. | +| [`ngx_http_limit_req_module`](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html) | Limits request rate. | +| [`ngx_http_log_module`](https://nginx.org/en/docs/http/ngx_http_log_module.html) | Logging support. | +| [`ngx_http_map_module`](https://nginx.org/en/docs/http/ngx_http_map_module.html) | Variable mapping logic. | +| [`ngx_http_memcached_module`](https://nginx.org/en/docs/http/ngx_http_memcached_module.html) | Memcached backend. | +| [`ngx_http_mirror_module`](https://nginx.org/en/docs/http/ngx_http_mirror_module.html) | Mirrors requests to another location. | +| [`ngx_http_proxy_module`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html) | HTTP reverse proxy. | +| [`ngx_http_referer_module`](https://nginx.org/en/docs/http/ngx_http_referer_module.html) | Referer-based access control.| +| [`ngx_http_rewrite_module`](https://nginx.org/en/docs/http/ngx_http_rewrite_module.html) | URL rewriting. | +| [`ngx_http_scgi_module`](https://nginx.org/en/docs/http/ngx_http_scgi_module.html) | SCGI backend. | +| [`ngx_http_split_clients_module`](https://nginx.org/en/docs/http/ngx_http_split_clients_module.html) | A/B testing logic. | +| [`ngx_http_ssi_module`](https://nginx.org/en/docs/http/ngx_http_ssi_module.html) | Server Side Includes. | +| [`ngx_http_upstream_module`](https://nginx.org/en/docs/http/ngx_http_upstream_module.html) | Upstream group and load balancing logic. | +| [`ngx_http_userid_module`](https://nginx.org/en/docs/http/ngx_http_userid_module.html) | Cookie-based user ID generation. | +| [`ngx_http_uwsgi_module`](https://nginx.org/en/docs/http/ngx_http_uwsgi_module.html) | uWSGI backend. | +{{}} + +### Statically linked modules + +In addition to core modules, the `nginx` package includes other nginx modules that do not require additional libraries to avoid extra dependencies. These modules are compiled at build time and specified using the` --with-` configure option. Unlike [dynamic modules](#dynamic-modules), they cannot be enabled or disabled dynamically after compilation. You can get the list of these modules in the output of the `nginx -V` command output in `configure arguments`. + +{{}} +|Module Name | Description | +| -------------------------| ---------------------------------------------| +| `--with-compat` |Enables dynamic modules compatibility. | +| `--with-file-aio` |Enables the use of [asynchronous file I/O](https:/ /nginx.org/en/docs/http/ngx_http_core_module.html#aio) (AIO) on FreeBSD and Linux. | +| `--with-threads` | Enables NGINX to use thread pools. For details, see [Thread Pools in NGINX Boost Performance 9x!](https://www.nginx.com/blog/thread-pools-boost-performance-9x/) on the NGINX blog. | +|[`--with-http_addition_module`](https://nginx.org/en/docs/http/ngx_http_addition_module.html)| Adds text before and after a response. | +|[`--with-http_auth_request_module`](https://nginx.org/en/docs/http/ngx_http_auth_request_module.html)|Implements client authorization based on the result of a subrequest. | +|[`--with-http_dav_module`](https://nginx.org/en/docs/http/ngx_http_dav_module.html)|Enables file management automation using the WebDAV protocol. | +|[`--with-http_flv_module`](https://nginx.org/en/docs/http/ngx_http_flv_module.html)|Provides pseudo-streaming server-side support for Flash Video (FLV) files. | +|[`--with-http_gunzip_module`](https://nginx.org/en/docs/http/ngx_http_gunzip_module.html)|Decompresses responses with `Content-Encoding: gzip` for clients that do not support the _zip_ encoding method. | +|[`--with-http_gzip_static_module`](https://nginx.org/en/docs/http/ngx_http_gzip_static_module.html)| Allows sending precompressed files with the **.gz** filename extension instead of regular files. | +|[`--with-http_mp4_module`](https://nginx.org/en/docs/http/ngx_http_mp4_module.html)| Provides pseudo-streaming server-side support for MP4 files. | +|[`--with-http_random_index_module`](https://nginx.org/en/docs/http/ngx_http_random_index_module.html) | Processes requests ending with the slash character (‘/’) and picks a random file in a directory to serve as an index file. | +|[`--with-http_realip_module`](https://nginx.org/en/docs/http/ngx_http_realip_module.html) | Changes the client address to the one sent in the specified header field. | +|[`--with-http_secure_link_module`](https://nginx.org/en/docs/http/ngx_http_secure_link_module.html) | Used to check authenticity of requested links, protect resources from unauthorized access, and limit link lifetime. | +|[`--with-http_slice_module`](https://nginx.org/en/docs/http/ngx_http_slice_module.html) | Allows splitting a request into subrequests, each subrequest returns a certain range of response. Provides more effective caching of large files. | +|[`--with-http_ssl_module`](https://nginx.org/en/docs/http/ngx_http_ssl_module.html) | Enables HTTPS support. Requires an SSL library such as [OpenSSL](https://www.openssl.org/). | +|[`--with-http_stub_status_module`](https://nginx.org/en/docs/http/ngx_http_stub_status_module.html)| Provides access to basic status information. Note that NGINX Plus customers do not require this module as they are already provided with extended status metrics and interactive dashboard. | +|[`--with-http_sub_module`](https://nginx.org/en/docs/http/ngx_http_sub_module.html) | Modifies a response by replacing one specified string by another. | +|[`--with-http_v2_module`](https://nginx.org/en/docs/http/ngx_http_v2_module.html)| Enable support for [HTTP/2](https://datatracker.ietf.org/doc/html/rfc7540). See [The HTTP/2 Module in NGINX](https://www.nginx.com/blog/http2-module-nginx/) on the NGINX blog for details.| +|[`--with-http_v3_module`](https://nginx.org/en/docs/http/ngx_http_v3_module.html)| Provides experimental support for [HTTP/3](https://datatracker.ietf.org/doc/html/rfc9114). | +|[`--with-mail`](https://nginx.org/en/docs/mail/ngx_mail_core_module.html)| Enables mail proxy functionality. To compile as a separate [dynamic module]({{< ref "/nginx/admin-guide/dynamic-modules/dynamic-modules.md" >}}) instead, change the option to `--with-mail=dynamic`. | +|[`--with-mail_ssl_module`](https://nginx.org/en/docs/mail/ngx_mail_ssl_module.html)| Provides support for a mail proxy server to work with the SSL/TLS protocol. Requires an SSL library such as [OpenSSL](https://www.openssl.org/). | +|[`--with-stream`](https://nginx.org/en/docs/stream/ngx_stream_core_module.html) | Enables the TCP and UDP proxy functionality. To compile as a separate [dynamic module]({{< ref "nginx/admin-guide/dynamic-modules/dynamic-modules.md" >}}) instead, change the option to `--with-stream=dynamic`. | +|[`--with-stream_realip_module`](https://nginx.org/en/docs/stream/ngx_stream_realip_module.html) | Changes the client address and port to the ones sent in the PROXY protocol header. | +|[`--with-stream_ssl_module`](https://nginx.org/en/docs/stream/ngx_stream_ssl_module.html)| Provides support for a stream proxy server to work with the SSL/TLS protocol. Requires an SSL library such as [OpenSSL](https://www.openssl.org/). | +{{}} + + +## Dynamic modules + +Some modules, especially those with external dependencies, are not included in the `nginx` package. However, they are available as separate packages from the official NGINX repository. After installation they can be connected as a dynamic modules, or shared object (.so) files via the `load_module` directive in the NGINX configuration. + +{{}} +|Module Name | Description | Package name | +| -------------------------| ---------------------------------------------|---------------| +| [`ngx_http_geoip_module`](https://nginx.org/en/docs/http/ngx_http_geoip_module.html) | Creates variables with values depending on the client IP address, using the precompiled MaxMind databases. | `nginx-module-geoip` | +| [`ngx_http_image-filter_module`](https://nginx.org/en/docs/http/ngx_http_image_filter_module.html)| Transforms images in JPEG, GIF, PNG, and WebP formats. | `nginx-module-image-filter` | +| [`ngx_http_js_module`](https://nginx.org/en/docs/http/ngx_http_js_module.html), [`ngx_stream_js_module`](https://nginx.org/en/docs/stream/ngx_stream_js_module.html)| Extends the server's functionality through JavaScript scripting, enabling the creation of custom server-side logic. | `nginx-module-njs` | +| [`ngx_http_perl_module`](https://nginx.org/en/docs/http/ngx_http_perl_module.html) | Implements location and variable handlers in Perl and inserts Perl calls into SSI. | `nginx-module-perl` | +| [`ngx_http_xsl_module`](https://nginx.org/en/docs/http/ngx_http_xslt_module.html) | Transforms XML responses using one or more XSLT stylesheets. | `nginx-module-xslt` | +| [`ngx_otel_module`](https://nginx.org/en/docs/ngx_otel_module.html) | Provides OpenTelemetry distributed tracing support. | `nginx-module-otel` | +{{}} + +## Compile and install from source {#sources} + +Compiling from source affords more flexibility than using prebuilt packages: you can add specific modules, both official and third party, and apply the latest security patches. + +### Install NGINX dependencies {#dependencies} + +Prior to compiling NGINX Open Source from source, you need to install libraries for its dependencies: - [PCRE](http://pcre.org/) – Supports regular expressions. Required by the NGINX [Core](https://nginx.org/en/docs/ngx_core_module.html) and [Rewrite](https://nginx.org/en/docs/http/ngx_http_rewrite_module.html) modules. ```shell - wget github.com/PCRE2Project/pcre2/releases/download/pcre2-10.43/pcre2-10.43.tar.gz - tar -zxf pcre2-10.43.tar.gz - cd pcre2-10.43 - ./configure - make + wget https://github.com/PCRE2Project/pcre2/releases/download/pcre2-10.43/pcre2-10.43.tar.gz && \ + tar -zxf pcre2-10.43.tar.gz && \ + cd pcre2-10.43 && \ + ./configure && \ + make && \ sudo make install ``` - [zlib](http://www.zlib.net/) – Supports header compression. Required by the NGINX [Gzip](https://nginx.org/en/docs/http/ngx_http_gzip_module.html) module. ```shell - wget http://zlib.net/zlib-1.3.1.tar.gz - tar -zxf zlib-1.3.1.tar.gz - cd zlib-1.3.1 - ./configure - make + wget http://zlib.net/zlib-1.3.1.tar.gz && \ + tar -zxf zlib-1.3.1.tar.gz && \ + cd zlib-1.3.1 && \ + ./configure && \ + make && \ sudo make install ``` @@ -717,50 +990,67 @@ Prior to compiling NGINX Open Source from source, you need to install librarie sudo make install ``` - -### Downloading the Sources + Example for Ubuntu and Debian: + ```shell + wget https://www.openssl.org/source/openssl-3.0.13.tar.gz + tar -zxf openssl-3.0.13.tar.gz + cd openssl-3.0.13 + ./config --prefix=/usr/local --openssldir=/usr/local/ssl + make -j$(nproc) + sudo make install + ``` + + Example for RHEL-based: + ```shell + curl -LO https://www.openssl.org/source/openssl-3.0.13.tar.gz + tar -zxf openssl-3.0.13.tar.gz + cd openssl-3.0.13 + ./config --prefix=/usr/local --openssldir=/usr/local/ssl + make -j$(nproc) + sudo make install + ``` + +### Download the sources {#sources_download} Download the source files for both the stable and mainline versions from [**nginx.org**](https://www.nginx.org/en/download.html). To download and unpack the source for the latest _mainline_ version, run: ```shell -wget https://nginx.org/download/nginx-1.27.4.tar.gz -tar zxf nginx-1.27.4.tar.gz -cd nginx-1.27.4 +wget https://nginx.org/download/nginx-1.27.5.tar.gz && \ +tar zxf nginx-1.27.5.tar.gz && \ +cd nginx-1.27.5 ``` To download and unpack source files for the latest _stable_ version, run: ```shell -wget https://nginx.org/download/nginx-1.26.3.tar.gz -tar zxf nginx-1.26.3.tar.gz -cd nginx-1.26.3 +wget https://nginx.org/download/nginx-1.28.0.tar.gz && \ +tar zxf nginx-1.28.0.tar.gz && \ +cd nginx-1.28.0 ``` - -### Configuring the Build Options +### Configure the build options {#configure} -Configure options are specified with the `./configure` script that sets up various NGINX parameters, including paths to source and configuration files, compiler options, connection processing methods, and the list of modules. The script finishes by creating the `Makefile` required to compile the code and install NGINX Open Source. +Configure options are specified with the `./configure` script that sets up various NGINX parameters, including paths to source and configuration files, compiler options, connection processing methods, and the list of modules. The script finishes by creating the `Makefile` required to compile the code and install NGINX Open Source. -An example of options to the `configure` script (should be typed as a single line): +An example of options to the `configure` script: ```shell -./configure ---sbin-path=/usr/local/nginx/nginx ---conf-path=/usr/local/nginx/nginx.conf ---pid-path=/usr/local/nginx/nginx.pid ---with-pcre=../pcre2-10.43 ---with-zlib=../zlib-1.3.1 ---with-http_ssl_module ---with-stream ---with-mail=dynamic ---add-module=/usr/build/nginx-rtmp-module +./configure \ +--sbin-path=/usr/local/nginx/nginx \ +--conf-path=/usr/local/nginx/nginx.conf \ +--pid-path=/usr/local/nginx/nginx.pid \ +--with-pcre=../pcre2-10.43 \ +--with-zlib=../zlib-1.3.1 \ +--with-http_ssl_module \ +--with-stream \ +--with-mail=dynamic \ +--add-module=/usr/build/nginx-rtmp-module \ --add-dynamic-module=/usr/build/3party_module ``` - -#### Configuring NGINX Paths +### Configure NGINX paths {#configure_paths} The `configure` script allows you to set paths to NGINX binary and configuration files, and to dependent libraries such as PCRE or SSL, in order to link them statically to the NGINX binary. @@ -770,23 +1060,21 @@ The `configure` script allows you to set paths to NGINX binary and configuration |Parameter | Description | | ---| --- | -|``--prefix=`` | Directory for NGINX files, and the base location for all relative paths set by the other `configure` script options (excluding paths to libraries) and for the path to the **nginx.conf** configuration file. Default: **/usr/local/nginx**. | -|``--sbin-path=`` | Name of the NGINX executable file, which is used only during installation. Default: **/sbin/nginx | -|``--conf-path=`` | Name of the NGINX configuration file. You can, however, always override this value at startup by specifying a different file with the ``-c `` option on the `nginx` command line. Default: **conf/nginx.conf | -|``--pid-path=`` | Name of the **nginx.pid** file, which stores the process ID of the `nginx` master process. After installation, the path to the filename can be changed with the [pid](https://nginx.org/en/docs/ngx_core_module.html#pid) directive in the NGINX configuration file. Default: **/logs/nginx.pid | -|``--error-log-path=`` | Name of the primary log file for errors, warnings, and diagnostic data. After installation, the filename can be changed with the [error_log](https://nginx.org/en/docs/ngx_core_module.html#error_log) directive in the NGINX configuration file. Default: **/logs/error.log | -|``--http-log-path=`` | Name of the primary log file for requests to the HTTP server. After installation, the filename can always be changed with the [access_log](https://nginx.org/en/docs/http/ngx_http_log_module.html#access_log) directive in the NGINX configuration file. Default: **/logs/access.log | -|``--user=`` | Name of the unprivileged user whose credentials are used by the NGINX worker processes. After installation, the name can be changed with the [user](https://nginx.org/en/docs/ngx_core_module.html#user) directive in the NGINX configuration file. Default: ``nobody`` | -|``--group=`` | Name of the group whose credentials are used by the NGINX worker processes. After installation, the name can be changed with the [user](https://nginx.org/en/docs/ngx_core_module.html#user) directive in the NGINX configuration file. Default: the value set by the ``--user`` option. | -|``--with-pcre=`` | Path to the source for the PCRE library, which is required for regular expressions support in the [location](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) directive and the [Rewrite](https://nginx.org/en/docs/http/ngx_http_rewrite_module.html) module. | -|``--with-pcre-jit`` | Builds the PCRE library with “just-in-time compilation” support (the [pcre_jit](https://nginx.org/en/docs/ngx_core_module.html#pcre_jit) directive). | -|``--with-zlib=`` | Path to the source for the `zlib` library, which is required by the [Gzip](https://nginx.org/en/docs/http/ngx_http_gzip_module.html) module. | - +|`--prefix=` | Directory for NGINX files, and the base location for all relative paths set by the other `configure` script options (excluding paths to libraries) and for the path to the **nginx.conf** configuration file. Default: **/usr/local/nginx**. | +|`--sbin-path=` | Name of the NGINX executable file, which is used only during installation. Default: **/sbin/nginx | +|`--conf-path=` | Name of the NGINX configuration file. You can, however, always override this value at startup by specifying a different file with the `-c ` option on the `nginx` command line. Default: **conf/nginx.conf | +|`--pid-path=` | Name of the **nginx.pid** file, which stores the process ID of the `nginx` master process. After installation, the path to the filename can be changed with the [pid](https://nginx.org/en/docs/ngx_core_module.html#pid) directive in the NGINX configuration file. Default: **/logs/nginx.pid | +|`--error-log-path=` | Name of the primary log file for errors, warnings, and diagnostic data. After installation, the filename can be changed with the [error_log](https://nginx.org/en/docs/ngx_core_module.html#error_log) directive in the NGINX configuration file. Default: **/logs/error.log | +|`--http-log-path=` | Name of the primary log file for requests to the HTTP server. After installation, the filename can always be changed with the [access_log](https://nginx.org/en/docs/http/ngx_http_log_module.html#access_log) directive in the NGINX configuration file. Default: **/logs/access.log | +|`--user=` | Name of the unprivileged user whose credentials are used by the NGINX worker processes. After installation, the name can be changed with the [user](https://nginx.org/en/docs/ngx_core_module.html#user) directive in the NGINX configuration file. Default: `nobody` | +|`--group=` | Name of the group whose credentials are used by the NGINX worker processes. After installation, the name can be changed with the [user](https://nginx.org/en/docs/ngx_core_module.html#user) directive in the NGINX configuration file. Default: the value set by the `--user`` option. | +|`--with-pcre=` | Path to the source for the PCRE library, which is required for regular expressions support in the [location](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) directive and the [Rewrite](https://nginx.org/en/docs/http/ngx_http_rewrite_module.html) module. | +|`--with-pcre-jit` | Builds the PCRE library with “just-in-time compilation” support (the [pcre_jit](https://nginx.org/en/docs/ngx_core_module.html#pcre_jit) directive). | +|`--with-zlib=` | Path to the source for the `zlib` library, which is required by the [Gzip](https://nginx.org/en/docs/http/ngx_http_gzip_module.html) module. | {{}} - -#### Configuring NGINX GCC Options +### GCC options {#configure_gcc} With the `configure` script you can also specify compiler‑related options. @@ -795,14 +1083,13 @@ With the `configure` script you can also specify compiler‑related options. |Parameter | Description | | ---| --- | -|``--with-cc-opt=""`` | Additional parameters that are added to the ``CFLAGS`` variable. When using the system PCRE library under FreeBSD, the mandatory value is ``--with-cc-opt="-I /usr/local/include"``. If the number of files supported by ``select()`` needs to be increased, it can also specified here as in this example: ``--with-cc-opt="-D FD_SETSIZE=2048"``. | -|``--with-ld-opt=""`` | Additional parameters that are used during linking. When using the system PCRE library under FreeBSD, the mandatory value is ``--with-ld-opt="-L /usr/local/lib"``. | +|`--with-cc-opt=""` | Additional parameters that are added to the ``CFLAGS`` variable. When using the system PCRE library under FreeBSD, the mandatory value is `--with-cc-opt="-I /usr/local/include"`. If the number of files supported by `select()` needs to be increased, it can also specified here as in this example: `--with-cc-opt="-D FD_SETSIZE=2048"`. | +|`--with-ld-opt=""` | Additional parameters that are used during linking. When using the system PCRE library under FreeBSD, the mandatory value is `--with-ld-opt="-L /usr/local/lib"`. | {{}} - -#### Specifying NGINX Connection Processing Methods +### Connection processing methods {#configure_methods} With the `configure` script you can redefine the method for event‑based polling. For more information, see [Connection processing methods](https://nginx.org/en/docs/events.html) in the NGINX reference documentation. @@ -811,15 +1098,12 @@ With the `configure` script you can redefine the method for event‑based pollin |Module Name | Description | | ---| --- | -|``--with-select_module``, ``--without-select_module`` | Enables or disables building a module that enable NGINX to work with the ``select()`` method. The modules is built automatically if the platform does not appear to support more appropriate methods such as `kqueue`, `epoll`, or `/dev/poll`. | -|``--with-poll_module``, ``--without-poll_module`` | Enables or disables building a module that enables NGINX to work with the ``poll()`` method. The module is built automatically if the platform does not appear to support more appropriate methods such as `kqueue`, `epoll`, or `/dev/poll`. | +|`--with-select_module`, `--without-select_module` | Enables or disables building a module that enable NGINX to work with the ``select()`` method. The modules is built automatically if the platform does not appear to support more appropriate methods such as `kqueue`, `epoll`, or `/dev/poll`. | +|`--with-poll_module`, `--without-poll_module` | Enables or disables building a module that enables NGINX to work with the `poll()` method. The module is built automatically if the platform does not appear to support more appropriate methods such as `kqueue`, `epoll`, or `/dev/poll`. | {{}} - - - -#### Selecting the NGINX Modules to Build +### Select the NGINX modules to build {#modules} NGINX consists of a set of function‑specific _modules_, which are specified with `configure` script along with other build options. @@ -827,193 +1111,128 @@ Some modules are built by default – they do not have to be specified with the Modules not included by default, as well as third‑party modules, must be explicitly specified in the `configure` script together with other build options. Such modules can be linked to NGINX binary either _statically_ (they are then loaded each time NGINX starts) or _dynamically_ (they are loaded only if associated directives are included in the NGINX configuration file. - -#### Modules Built by Default +#### Modules built by default {#modules_default} If you do not need a module that is built by default, you can disable it by naming it with the `--without-` option on the `configure` script, as in this example which disables the [Empty GIF](https://nginx.org/en/docs/http/ngx_http_empty_gif_module.html) module (should be typed as a single line): ```shell ./configure ---sbin-path=/usr/local/nginx/nginx ---conf-path=/usr/local/nginx/nginx.conf ---pid-path=/usr/local/nginx/nginx.pid ---with-http_ssl_module ---with-stream ---with-pcre=../pcre2-10.43 ---with-zlib=../zlib-1.3.1 +--sbin-path=/usr/local/nginx/nginx \ +--conf-path=/usr/local/nginx/nginx.conf \ +--pid-path=/usr/local/nginx/nginx.pid \ +--with-http_ssl_module \ +--with-stream \ +--with-pcre=../pcre2-10.43 \ +--with-zlib=../zlib-1.3.1 \ --without-http_empty_gif_module ``` - - {{}} |Module Name | Description | | ---| --- | -|[http_access_module](https://nginx.org/en/docs/http/ngx_http_access_module.html) | Accepts or denies requests from specified client addresses. | -|[http_auth_basic_module](https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html) | Limits access to resources by validating the user name and password using the HTTP Basic Authentication protocol. | -|[http_autoindex_module](https://nginx.org/en/docs/http/ngx_http_autoindex_module.html) | Processes requests ending with the forward-slash character (_/_) and produces a directory listing. | -|[http_browser_module](https://nginx.org/en/docs/http/ngx_http_browser_module.html) | Creates variables whose values depend on the value of the ``User-Agent`` request header. | -|[http_charset_module](https://nginx.org/en/docs/http/ngx_http_charset_module.html) | Adds the specified character set to the ``Content-Type`` response header. Can convert data from one character set to another. | -|[http_empty_gif_module](https://nginx.org/en/docs/http/ngx_http_empty_gif_module.html) | Emits a single-pixel transparent GIF. | -|[http_fastcgi_module](https://nginx.org/en/docs/http/ngx_http_fastcgi_module.html) | Passes requests to a FastCGI server. | -|[http_geo_module](https://nginx.org/en/docs/http/ngx_http_geo_module.html) | Creates variables with values that depend on the client IP address. | -|[http_gzip_module](https://nginx.org/en/docs/http/ngx_http_gzip_module.html) | Compresses responses using `gzip`, reducing the amount of transmitted data by half or more. | -|[http_limit_conn_module](https://nginx.org/en/docs/http/ngx_http_limit_conn_module.html) | Limits the number of connections per a defined key, in particular, the number of connections from a single IP address. | -|[http_limit_req_module](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html) | Limits the request processing rate per a defined key, in particular, the processing rate of requests coming from a single IP address. | -|[http_map_module](https://nginx.org/en/docs/http/ngx_http_map_module.html) | Creates variables whose values depend on the values of other variables. | -|[http_memcached_module](https://nginx.org/en/docs/http/ngx_http_memcached_module.html) | Passes requests to a memcached server. | -|[http_proxy_module](https://nginx.org/en/docs/http/ngx_http_proxy_module.html) | Passes HTTP requests to another server. | -|[http_referer_module](https://nginx.org/en/docs/http/ngx_http_referer_module.html) | Blocks requests with invalid values in the `Referer` header. | -|[http_rewrite_module](https://nginx.org/en/docs/http/ngx_http_rewrite_module.html) | Changes the request URI using regular expressions and return redirects; conditionally selects configurations. Requires the [PCRE](http://pcre.org/) library. | -|[http_scgi_module](https://nginx.org/en/docs/http/ngx_http_scgi_module.html) | Passes requests to an SCGI server. | -|[http_ssi_module](https://nginx.org/en/docs/http/ngx_http_ssi_module.html) | Processes SSI (Server Side Includes) commands in responses passing through it. | -|[http_split_clients_module](https://nginx.org/en/docs/http/ngx_http_split_clients_module.html) | Creates variables suitable for A/B testing, also known as split testing. | -|[http_upstream_hash_module](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#hash) | Enables the generic Hash load-balancing method. | -|[http_upstream_ip_hash_module](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#ip_hash) | Enables the IP Hash load-balancing method. | -|[http_upstream_keepalive_module](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive) | Enables keepalive connections. | -|[http_upstream_least_conn_module](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#least_conn) | Enables the Least Connections load-balancing method. | -|[http_upstream_zone_module](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#zone) | Enables shared memory zones. | -|[http_userid_module](https://nginx.org/en/docs/http/ngx_http_userid_module.html) | Sets cookies suitable for client identification. | -|[http_uwsgi_module](https://nginx.org/en/docs/http/ngx_http_uwsgi_module.html) | Passes requests to a uwsgi server. | - +|[`http_access_module`](https://nginx.org/en/docs/http/ngx_http_access_module.html) | Accepts or denies requests from specified client addresses. | +|[`http_auth_basic_module`](https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html) | Limits access to resources by validating the user name and password using the HTTP Basic Authentication protocol. | +|[`http_autoindex_module`](https://nginx.org/en/docs/http/ngx_http_autoindex_module.html) | Processes requests ending with the forward-slash character (_/_) and produces a directory listing. | +|[`http_browser_module`](https://nginx.org/en/docs/http/ngx_http_browser_module.html) | Creates variables whose values depend on the value of the ``User-Agent`` request header. | +|[`http_charset_module`](https://nginx.org/en/docs/http/ngx_http_charset_module.html) | Adds the specified character set to the ``Content-Type`` response header. Can convert data from one character set to another. | +|[`http_empty_gif_module`](https://nginx.org/en/docs/http/ngx_http_empty_gif_module.html) | Emits a single-pixel transparent GIF. | +|[`http_fastcgi_module`](https://nginx.org/en/docs/http/ngx_http_fastcgi_module.html) | Passes requests to a FastCGI server. | +|[`http_geo_module`](https://nginx.org/en/docs/http/ngx_http_geo_module.html) | Creates variables with values that depend on the client IP address. | +|[`http_gzip_module`](https://nginx.org/en/docs/http/ngx_http_gzip_module.html) | Compresses responses using `gzip`, reducing the amount of transmitted data by half or more. | +|[`http_limit_conn_module`](https://nginx.org/en/docs/http/ngx_http_limit_conn_module.html) | Limits the number of connections per a defined key, in particular, the number of connections from a single IP address. | +|[`http_limit_req_module`](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html) | Limits the request processing rate per a defined key, in particular, the processing rate of requests coming from a single IP address. | +|[`http_map_module`](https://nginx.org/en/docs/http/ngx_http_map_module.html) | Creates variables whose values depend on the values of other variables. | +|[`http_memcached_module`](https://nginx.org/en/docs/http/ngx_http_memcached_module.html) | Passes requests to a memcached server. | +|[`http_proxy_module`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html) | Passes HTTP requests to another server. | +|[`http_referer_module`](https://nginx.org/en/docs/http/ngx_http_referer_module.html) | Blocks requests with invalid values in the `Referer` header. | +|[`http_rewrite_module`](https://nginx.org/en/docs/http/ngx_http_rewrite_module.html) | Changes the request URI using regular expressions and return redirects; conditionally selects configurations. Requires the [PCRE](http://pcre.org/) library. | +|[`http_scgi_module`](https://nginx.org/en/docs/http/ngx_http_scgi_module.html) | Passes requests to an SCGI server. | +|[`http_ssi_module`](https://nginx.org/en/docs/http/ngx_http_ssi_module.html) | Processes SSI (Server Side Includes) commands in responses passing through it. | +|[`http_split_clients_module`](https://nginx.org/en/docs/http/ngx_http_split_clients_module.html) | Creates variables suitable for A/B testing, also known as split testing. | +|[`http_upstream_hash_module`](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#hash) | Enables the generic Hash load-balancing method. | +|[`http_upstream_ip_hash_module`](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#ip_hash) | Enables the IP Hash load-balancing method. | +|[`http_upstream_keepalive_module`](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive) | Enables keepalive connections. | +|[`http_upstream_least_conn_module`](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#least_conn) | Enables the Least Connections load-balancing method. | +|[`http_upstream_zone_module`](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#zone) | Enables shared memory zones. | +|[`http_userid_module`](https://nginx.org/en/docs/http/ngx_http_userid_module.html) | Sets cookies suitable for client identification. | +|[`http_uwsgi_module`](https://nginx.org/en/docs/http/ngx_http_uwsgi_module.html) | Passes requests to a uwsgi server. | {{}} - -#### Including Modules Not Built by Default +### Include modules not built by default {#modules_not_default} Many NGINX modules are not built by default, and must be listed on the `configure` command line to be built. -The [mail](https://nginx.org/en/docs/mail/ngx_mail_core_module.html), [stream](https://nginx.org/en/docs/stream/ngx_stream_core_module.html), [geoip](https://nginx.org/en/docs/http/ngx_http_geoip_module.html), [image_filter](https://nginx.org/en/docs/http/ngx_http_image_filter_module.html), [perl](https://nginx.org/en/docs/http/ngx_http_perl_module.html) and [xslt](https://nginx.org/en/docs/http/ngx_http_xslt_module.html) modules can be compiled as dynamic. See [Dynamic Modules]({{< ref "nginx/admin-guide/dynamic-modules/dynamic-modules.md" >}}) for details. +The [mail](https://nginx.org/en/docs/mail/ngx_mail_core_module.html), [stream](https://nginx.org/en/docs/stream/ngx_stream_core_module.html), [geoip](https://nginx.org/en/docs/http/ngx_http_geoip_module.html), [image_filter](https://nginx.org/en/docs/http/ngx_http_image_filter_module.html), [perl](https://nginx.org/en/docs/http/ngx_http_perl_module.html) and [xslt](https://nginx.org/en/docs/http/ngx_http_xslt_module.html) modules can be compiled as dynamic. See [Dynamic Modules]({{< ref "/nginx/admin-guide/dynamic-modules/dynamic-modules.md" >}}) for details. An example of the `configure` command that includes nondefault modules (should be typed as a single line): ```shell -./configure ---sbin-path=/usr/local/nginx/nginx ---conf-path=/usr/local/nginx/nginx.conf ---pid-path=/usr/local/nginx/nginx.pid ---with-pcre=../pcre2-10.43 ---with-zlib=../zlib-1.3.1 ---with-http_ssl_module ---with-stream +./configure \ +--sbin-path=/usr/local/nginx/nginx \ +--conf-path=/usr/local/nginx/nginx.conf \ +--pid-path=/usr/local/nginx/nginx.pid \ +--with-pcre=../pcre2-10.43 \ +--with-zlib=../zlib-1.3.1 \ +--with-http_ssl_module \ +--with-stream \ --with-mail ``` -{{}} - -|Module Name | Description | -| ---| --- | - +{{}} +|Module Name | Description | +| -------------------------| ---------------------------------------------| +|`--with-cpp_test_module` | Tests the C++ compatibility of header files.| +|`--with-debug` | Enables the [debugging log]({{< ref "/nginx/admin-guide/monitoring/debugging.md" >}})| +| `--with-file-aio` |Enables asynchronous I/O. | +| `--with-google-perftools` | Allows using [Google Performance tools](https://github.com/gperftools/gperftools) library. | +|[`--with-http_addition_module`](https://nginx.org/en/docs/http/ngx_http_addition_module.html)| Adds text before and after a response. | +|[`--with-http_auth_request_module`](https://nginx.org/en/docs/http/ngx_http_auth_request_module.html)|Implements client authorization based on the result of a subrequest. | +|[`--with-http_dav_module`](https://nginx.org/en/docs/http/ngx_http_dav_module.html)|Enables file management automation using the WebDAV protocol. | +|`--with-http_degradation_module`|Allows returning an error when a memory size exceeds the defined value. | +|[`--with-http_flv_module`](https://nginx.org/en/docs/http/ngx_http_flv_module.html)|Provides pseudo-streaming server-side support for Flash Video (FLV) files. | +|[`--with-http_geoip_module`](https://nginx.org/en/docs/http/ngx_http_geoip_module.html)|Enables creating variables whose values depend on the client IP address. The module uses [MaxMind](http://www.maxmind.com) GeoIP databases. To compile as a separate [dynamic module]({{< ref "/nginx/admin-guide/dynamic-modules/dynamic-modules.md" >}}) instead, change the option to `--with-http_geoip_module=dynamic`. | +|[`--with-http_gunzip_module`](https://nginx.org/en/docs/http/ngx_http_gunzip_module.html)|Decompresses responses with `Content-Encoding: gzip` for clients that do not support the _zip_ encoding method. | +|[`--with-http_gzip_static_module`](https://nginx.org/en/docs/http/ngx_http_gzip_static_module.html)| Allows sending precompressed files with the **.gz** filename extension instead of regular files. | +|[`--with-http_image_filter_module`](https://nginx.org/en/docs/http/ngx_http_image_filter_module.html)|T ransforms images in JPEG, GIF, and PNG formats. The module requires the [LibGD](http://libgd.github.io/) library. To compile as a separate [dynamic module]({{< ref "/nginx/admin-guide/dynamic-modules/dynamic-modules.md" >}}) instead, change the option to `--with-http_image_filter_module=dynamic`. | +|[`--with-http_mp4_module`](https://nginx.org/en/docs/http/ngx_http_mp4_module.html)| Provides pseudo-streaming server-side support for MP4 files. | +|[`--with-http_perl_module`](https://nginx.org/en/docs/http/ngx_http_perl_module.html)| Used to implement location and variable handlers in Perl and insert Perl calls into SSI. Requires the [PERL](https://www.perl.org/get.html) library. To compile as a separate [dynamic module]({{< ref "/nginx/admin-guide/dynamic-modules/dynamic-modules.md" >}}) instead, change the option to `--with-http_perl_module=dynamic`. | +|[`--with-http_random_index_module`](https://nginx.org/en/docs/http/ngx_http_random_index_module.html) | Processes requests ending with the slash character (‘/’) and picks a random file in a directory to serve as an index file. | +|[`--with-http_realip_module`](https://nginx.org/en/docs/http/ngx_http_realip_module.html) | Changes the client address to the one sent in the specified header field. | +|[`--with-http_secure_link_module`](https://nginx.org/en/docs/http/ngx_http_secure_link_module.html) | Used to check authenticity of requested links, protect resources from unauthorized access, and limit link lifetime. | +|[`--with-http_slice_module`](https://nginx.org/en/docs/http/ngx_http_slice_module.html) | Allows splitting a request into subrequests, each subrequest returns a certain range of response. Provides more effective caching of large files. | +|[`--with-http_ssl_module`](https://nginx.org/en/docs/http/ngx_http_ssl_module.html) | Enables HTTPS support. Requires an SSL library such as [OpenSSL](https://www.openssl.org/). | +|[`--with-http_stub_status_module`](https://nginx.org/en/docs/http/ngx_http_stub_status_module.html)| Provides access to basic status information. Note that NGINX Plus customers do not require this module as they are already provided with extended status metrics and interactive dashboard. | +|[`--with-http_sub_module`](https://nginx.org/en/docs/http/ngx_http_sub_module.html) | Modifies a response by replacing one specified string by another. | +|[`--with-http_xslt_module`](https://nginx.org/en/docs/http/ngx_http_xslt_module.html)| Transforms XML responses using one or more XSLT stylesheets. The module requires the [Libxml2](http://xmlsoft.org/) and [XSLT](http://xmlsoft.org/XSLT/) libraries. To compile as a separate [dynamic module]({{< ref "/nginx/admin-guide/dynamic-modules/dynamic-modules.md" >}}) instead, change the option to `--with-http_xslt_module=dynamic`. | +|[`--with-http_v2_module`](https://nginx.org/en/docs/http/ngx_http_v2_module.html)| Enable support for [HTTP/2](https://datatracker.ietf.org/doc/html/rfc7540). See [The HTTP/2 Module in NGINX](https://www.nginx.com/blog/http2-module-nginx/) on the NGINX blog for details. | +| [`--with-mail`](https://nginx.org/en/docs/mail/ngx_mail_core_module.html)| Enables mail proxy functionality. To compile as a separate [dynamic module]({{< ref "/nginx/admin-guide/dynamic-modules/dynamic-modules.md" >}}) instead, change the option to `--with-mail=dynamic`. | +|[`--with-mail_ssl_module`](https://nginx.org/en/docs/mail/ngx_mail_ssl_module.html)| Provides support for a mail proxy server to work with the SSL/TLS protocol. Requires an SSL library such as [OpenSSL](https://www.openssl.org/). | +| [`--with-stream`](https://nginx.org/en/docs/stream/ngx_stream_core_module.html) | Enables the TCP and UDP proxy functionality. To compile as a separate [dynamic module]({{< ref "/nginx/admin-guide/dynamic-modules/dynamic-modules.md" >}}) instead, change the option to `--with-stream=dynamic`. | +| [`--with-stream_ssl_module`](https://nginx.org/en/docs/stream/ngx_stream_ssl_module.html)| Provides support for a stream proxy server to work with the SSL/TLS protocol. Requires an SSL library such as [OpenSSL](https://www.openssl.org/). | +| `--with-threads` | Enables NGINX to use thread pools. For details, see [Thread Pools in NGINX Boost Performance 9x!](https://www.nginx.com/blog/thread-pools-boost-performance-9x/) on the NGINX blog. | {{}} -- - ``--with-cpp_test_module`` - - Tests the C++ compatibility of header files. - -- - ``--with-debug`` - - Enables the [debugging log](https://docs.nginx.com/nginx/admin-guide/monitoring/debugging/). - -- - ``--with-file-aio`` - - Enables asynchronous I/O. - - - Allows using [Google Performance tools](https://github.com/gperftools/gperftools) library. - -- - ``--`` [with-http_addition_module](https://nginx.org/en/docs/http/ngx_http_addition_module.html) - - Adds text before and after a response. - -- - ``--`` [with-http_auth_request_module](https://nginx.org/en/docs/http/ngx_http_auth_request_module.html) - - Implements client authorization based on the result of a subrequest. - -- - ``--`` [with-http_dav_module](https://nginx.org/en/docs/http/ngx_http_dav_module.html) - - Enables file management automation using the WebDAV protocol. - -- - ``--with-http_degradation_module`` - - Allows returning an error when a memory size exceeds the defined value. - -- - ``--`` [with-http_flv_module](https://nginx.org/en/docs/http/ngx_http_flv_module.html) - - Provides pseudo-streaming server-side support for Flash Video (FLV) files. - -- - ``--`` [with-http_geoip_module](https://nginx.org/en/docs/http/ngx_http_geoip_module.html) - - Enables creating variables whose values depend on the client IP address. The module uses [MaxMind](http://www.maxmind.com) GeoIP databases. To compile as a separate [dynamic module](https://docs.nginx.com/nginx/admin-guide/dynamic-modules/dynamic-modules/) instead, change the option to `--with-http_geoip_module=dynamic`. - -- - ``--`` [with-http_gunzip_module](https://nginx.org/en/docs/http/ngx_http_gunzip_module.html) - - Decompresses responses with `Content-Encoding: gzip` for clients that do not support the _zip_ encoding method. - -- - ``--`` [with-http_gzip_static_module](https://nginx.org/en/docs/http/ngx_http_gzip_static_module.html) - - Allows sending precompressed files with the **.gz** filename extension instead of regular files. - -- - ``--`` [with-http_image_filter_module](https://nginx.org/en/docs/http/ngx_http_image_filter_module.html) - - Transforms images in JPEG, GIF, and PNG formats. The module requires the [LibGD](http://libgd.github.io/) library. To compile as a separate [dynamic module](https://docs.nginx.com/nginx/admin-guide/dynamic-modules/dynamic-modules/) instead, change the option to ``--with-http_image_filter_module=dynamic``. - -- - ``--`` [with-http_mp4_module](https://nginx.org/en/docs/http/ngx_http_mp4_module.html) - - Provides pseudo-streaming server-side support for MP4 files. - -- - ``--`` [with-http_perl_module](https://nginx.org/en/docs/http/ngx_http_perl_module.html) - - Used to implement location and variable handlers in Perl and insert Perl calls into SSI. Requires the [PERL](https://www.perl.org/get.html) library. To compile as a separate [dynamic module](https://docs.nginx.com/nginx/admin-guide/dynamic-modules/dynamic-modules/) instead, change the option to ``--with-http_perl_module=dynamic``. - -- - ``--`` [with-http_random_index_module](https://nginx.org/en/docs/http/ngx_http_random_index_module.html) - - Processes requests ending with the slash character (‘/’) and picks a random file in a directory to serve as an index file. - -- - ``--`` [with-http_realip_module](https://nginx.org/en/docs/http/ngx_http_realip_module.html) - - Changes the client address to the one sent in the specified header field. - -- - ``--`` [with-http_secure_link_module](https://nginx.org/en/docs/http/ngx_http_secure_link_module.html) - - Used to check authenticity of requested links, protect resources from unauthorized access, and limit link lifetime. - -- - ``--`` [with-http_slice_module](https://nginx.org/en/docs/http/ngx_http_slice_module.html) - - Allows splitting a request into subrequests, each subrequest returns a certain range of response. Provides more effective caching of large files. - -- - ``--`` [with-http_ssl_module](https://nginx.org/en/docs/http/ngx_http_ssl_module.html) - - Enables HTTPS support. Requires an SSL library such as [OpenSSL](https://www.openssl.org/). - -- - ``--`` [with-http_stub_status_module](https://nginx.org/en/docs/http/ngx_http_stub_status_module.html) - - Provides access to basic status information. Note that NGINX Plus customers do not require this module as they are already provided with extended status metrics and interactive dashboard. - -- - ``--`` [with-http_sub_module](https://nginx.org/en/docs/http/ngx_http_sub_module.html) - - Modifies a response by replacing one specified string by another. - -- - ``--`` [with-http_xslt_module](https://nginx.org/en/docs/http/ngx_http_xslt_module.html) - - Transforms XML responses using one or more XSLT stylesheets. The module requires the [Libxml2](http://xmlsoft.org/) and [XSLT](http://xmlsoft.org/XSLT/) libraries. To compile as a separate [dynamic module](https://docs.nginx.com/nginx/admin-guide/dynamic-modules/dynamic-modules/) instead, change the option to ``--with-http_xslt_module=dynamic``. - -- - ``--`` [with-http_v2_module](https://nginx.org/en/docs/http/ngx_http_v2_module.html) - - Enable support for [HTTP/2](https://datatracker.ietf.org/doc/html/rfc7540). See [The HTTP/2 Module in NGINX](https://www.nginx.com/blog/http2-module-nginx/) on the NGINX blog for details. - -- - ``--`` [with-mail](https://nginx.org/en/docs/mail/ngx_mail_core_module.html) - - Enables mail proxy functionality. To compile as a separate [dynamic module](https://docs.nginx.com/nginx/admin-guide/dynamic-modules/dynamic-modules/) instead, change the option to ``--with-mail=dynamic``. - -- - ``--`` [with-mail_ssl_module](https://nginx.org/en/docs/mail/ngx_mail_ssl_module.html) - - Provides support for a mail proxy server to work with the SSL/TLS protocol. Requires an SSL library such as [OpenSSL](https://www.openssl.org/). - -- - ``--`` [with-stream](https://nginx.org/en/docs/stream/ngx_stream_core_module.html) - - Enables the TCP and UDP proxy functionality. To compile as a separate [dynamic module](https://docs.nginx.com/nginx/admin-guide/dynamic-modules/dynamic-modules/) instead, change the option to ``--with-stream=dynamic``. - -- - ``--`` [with-stream_ssl_module](https://nginx.org/en/docs/stream/ngx_stream_ssl_module.html) - - Provides support for a stream proxy server to work with the SSL/TLS protocol. Requires an SSL library such as [OpenSSL](https://www.openssl.org/). - -- - ``--with-threads`` - - Enables NGINX to use thread pools. For details, see [Thread Pools in NGINX Boost Performance 9x!](https://www.nginx.com/blog/thread-pools-boost-performance-9x/) on the NGINX blog. - -#### Including Third-Party Modules +### Include third-party modules -You can extend NGINX functionality by compiling NGINX Open Source with your own module or a third‑party module. Some third‑party modules are listed in the [NGINX Wiki](https://nginx.com/resources/wiki/modules/). Use third‑party modules at your own risk as their stability is not guaranteed. +You can extend NGINX functionality by compiling NGINX Open Source with your own module or a third‑party module. Some third‑party modules are listed in the [NGINX Wiki](https://nginx.com/resources/wiki/modules/). Use third‑party modules at your own risk as their stability is not guaranteed. - -##### Statically Linked Modules +#### Statically linked modules {#modules_third_party} -Most modules built into NGINX Open Source are _statically linked_: they are built into NGINX Open Source at compile time and are linked to the NGINX binary statically. These modules can be disabled only by recompiling NGINX. +Most modules built into NGINX Open Source are _statically linked_: they are built into NGINX Open Source at compile time and are linked to the NGINX binary statically. These modules can be disabled only by recompiling NGINX. -To compile NGINX Open Source with a statically linked third‑party module, include the `--add-module=` option on the `configure` command, where `` is the path to the source code (this example is for the [RTMP](https://github.com/arut/nginx-rtmp-module) module): +To compile NGINX Open Source with a statically linked third‑party module, include the `--add-module=` option on the `configure` command, where `` is the path to the source code (this example is for the [RTMP](https://github.com/arut/nginx-rtmp-module) module): ```shell ./configure ... --add-module=/usr/build/nginx-rtmp-module ``` -##### Dynamically Linked Modules +#### Dynamically linked modules -NGINX modules can also be compiled as a shared object (**\*.so** file) and then dynamically loaded into NGINX Open Source at runtime. This provides more flexibility, as the module can be loaded or unloaded at any time by adding or removing the associated [load_module](https://nginx.org/en/docs/ngx_core_module.html#load_module) directive in the NGINX configuration file and reloading the configuration. Note that the module itself must support dynamic linking. +NGINX modules can also be compiled as a shared object (**\*.so** file) and then dynamically loaded into NGINX Open Source at runtime. This provides more flexibility, as the module can be loaded or unloaded at any time by adding or removing the associated [`load_module`](https://nginx.org/en/docs/ngx_core_module.html#load_module) directive in the NGINX configuration file and reloading the configuration. Note that the module itself must support dynamic linking. -To compile NGINX Open Source with a dynamically loaded third‑party module, include the `--add-dynamic-module=` option on the `configure` command, where `` is the path to the source code: +To compile NGINX Open Source with a dynamically loaded third‑party module, include the `--add-dynamic-module=` option on the `configure` command, where `` is the path to the source code: ```shell @@ -1022,7 +1241,7 @@ To compile NGINX Open Source with a dynamically loaded third‑party module, i The resulting **\*.so** files are written to the _prefix_**/modules/** directory, where the _prefix_ is a directory for server files such as **/usr/local/nginx/**. -To load a dynamic module, add the [load_module](https://nginx.org/en/docs/ngx_core_module.html#load_module) directive to the NGINX configuration after installation: +To load a dynamic module, add the [`load_module`](https://nginx.org/en/docs/ngx_core_module.html#load_module) directive to the NGINX configuration after installation: ```nginx load_module modules/ngx_mail_module.so; @@ -1030,8 +1249,7 @@ load_module modules/ngx_mail_module.so; For more information, see [Compiling Third‑Party Dynamic Modules for NGINX and NGINX Plus](https://www.nginx.com/blog/compiling-dynamic-modules-nginx-plus/) on the NGINX blog and [Extending NGINX](https://nginx.com/resources/wiki/extending/) in the Wiki. - -### Completing the Installation from Source +### Complete the installation from source {#install_complete} - Compile and install the build: @@ -1040,7 +1258,7 @@ For more information, see [Compiling Third‑Party Dynamic Modules for NGINX and sudo make install ``` -- After the installation is finished, start NGINX Open Source: +- After the installation is finished, start NGINX Open Source: ```shell sudo nginx