NGINX Multiple Instances

This guide outlines the procedures for identifying, deploying, and upgrading NGINX Open Source web server instances using integrated scanner mechanisms and automated workflows.

NGINX Open Source is a web server that is also used as a reverse proxy, load balancer, and HTTP cache. BigFix supports patching NGINX Open Source to the stable release. Two patching methods are available:

  • Repository-based patching (Linux only): NGINX installed from the official NGINX Open Source repository as RPM or Debian packages is updated through the system package manager.
  • Scanner-based patching (Linux and Windows): NGINX installed from tar.gz (Linux) or ZIP (Windows) archives is detected by the Middleware Scanner and updated in place.

Repo-Based (Non-Scanner) Integration Process

Repository-based patching applies to NGINX Open Source installed as a package on the following distributions:

  • RHEL family: RPM packages.
  • Debian family: DEB packages.

Prerequisite: The official NGINX Open Source repository must be configured on the endpoint. The patching task uses the configured repository to retrieve the stable version. If the repository is not configured, the task fails.

Fixlets continuously evaluate target endpoints to check if the installed version is lower than the current stable target version. When applicable, native package management operations execute package updates automatically.

Note: For repository configuration instructions, refer to the official NGINX Linux packages documentation.

Scanner Process

For running the scans on all software versions, refer to BigFix Scanner for Middleware Application. These results are then used by the NGINX patching tasks to determine which instances require updates.

Note: Before performing any patching activity, it is highly recommended to create a full backup of all configuration files (for example, nginx.conf and the conf/ directory) and environment-specific settings. This ensures that you can restore your configuration if required after the patching process.
Note: The scanner-based detection mechanism identifies only tar.gz-based (Linux) and ZIP-based (Windows) installations. Package-based installations are handled by repository-based patching. For more information, refer to the official NGINX documentation.

Mandatory Pre-Patching Prerequisites

Before applying the patch, the following conditions must be met to ensure successful execution:

  • Configuration Backup: Back up the configuration files of each NGINX instance before patching.
  • Service Downtime: NGINX binaries cannot be replaced while the server is running. You must stop the Windows Service or the Linux daemon before patching.
  • Compilation Tools (Linux, tar.gz-based only): The environment requires gcc (or an equivalent C compiler), GNU make, and the development headers for PCRE, zlib, and OpenSSL to compile the source code into executable binaries.
  • Repository Access (Linux, package-based only): The official NGINX Open Source repository must be configured and reachable from the endpoint.

Patching Process

The NGINX patching task uses the scanner results to identify lower versions and update them to the stable version specified in the task.

  1. Select the applicable computer in the BigFix Console to review installed NGINX versions.
  2. When the action is executed on the endpoint, the patching task reads the results.xml file and identifies all NGINX instances present on the system.
  3. For Windows (ZIP-based): The task downloads the stable version ZIP archive, extracts it, and copies the contents over each detected installation path. All outdated versions are updated in a single execution. After the update, the task runs nginx -v to verify the installed version. Verify that no background nginx.exe processes are running if the patching process fails.
  4. For Linux (tar.gz-based): The task downloads the stable version source archive and extracts it in the middleware/nginx directory. The binaries must then be built and installed manually as described in the next section.
  5. For Linux (package-based): The task updates the nginx package from the configured official repository using the system package manager.

The upgrade process follows a structured sequence to ensure minimal downtime and configuration integrity.

Building and Installing Binaries

The task involves executing the configuration prior to building the binaries.

For Linux: Users must compile and install the updated binaries by running the configure (with custom path and the build options), make, and make install commands from within the extracted folder middleware/nginx/<version>. After a successful installation, the user needs to run make clean. Repeat the above process for each of the detected instances (custom path) in the mw_results.xml file.
./configure --prefix=<path>
make -j $(nproc)
make install
make clean
Note: If the configure step fails, verify that all required compilation dependencies and development headers are installed and properly configured.

Exit codes and their meanings

When performing tasks such as patching or extracting files in NGINX, certain exit codes may be returned to indicate the outcome of the operation. These codes help identify issues during the installation or update process.

Table 1. Exit codes and their meanings
Exit code Action
Exit Code 12: Results and/or JSON file not present
  • Check if the results and/or JSON file are present in the specified folder.
  • Run the scanner task again to generate the above files with the latest versions of the installed Nginx instances.
Exit Code 13: Archive file not found
  • Verify that the download link is correct and the file is accessible.
  • Ensure the file exists at the specified location.
Exit Code 14: Patching of one or more instances failed
  • Run the discovery task again to retrieve the latest versions of the installed Nginx instances.
  • Ensure that all instances are properly configured and accessible.