Nginx Web Server

HTTP/2 & HTTP/3 QUIC Support

HTTP/2 is enabled by default in all Centmin Mod Nginx builds via the NGINX_HTTP2='y' compile-time variable — no configuration needed. It includes HPACK header compression for faster page loads.

HTTP/3 is a newer protocol that uses QUIC (a UDP-based transport) instead of TCP. It provides faster initial connections, better performance on mobile networks and high-latency links, and eliminates head-of-line blocking that can slow down HTTP/2. Enable HTTP/3 QUIC by setting NGINX_QUIC_SUPPORT='y' before Nginx compilation, and opening UDP port 443 in your firewall (e.g., add 443 to UDP_IN and UDP_OUT in /etc/csf/csf.conf if using CSF).

Note: Nginx still considers HTTP/3 QUIC support experimental. It works well in practice but is not yet marked as stable by the Nginx project.

For historical reference on the original HTTP/2 transition from SPDY in Nginx 1.9.5 (2015), including migration steps and benchmarks, see the Nginx HTTP/2 Protocol archive page.

Quick Start: Recommended Setup (AWS-LC)

Add the following line to /etc/centminmod/custom_config.inc, then run centmin.sh menu option 4 to recompile Nginx. If you’re doing a fresh Centmin Mod installation, add it before running the installer:

Alternative Crypto Libraries for HTTP/3

If AWS-LC doesn’t suit your needs (for example, you need Lua modules or you’re on CentOS 7), two other libraries also provide HTTP/3 support:

Configuring Your Nginx Vhosts for HTTP/3

Your existing vhost config file (typically at /usr/local/nginx/conf/conf.d/yourdomain.com.ssl.conf) already contains listen lines for HTTPS over TCP. To enable HTTP/3, add new listen lines for QUIC over UDP, plus a header that tells browsers your site supports HTTP/3.

First vhost on this IP:port — with reuseport:

Additional vhosts on the same IP:port — without reuseport:

After editing your vhost files, test the configuration and restart Nginx:

For a detailed step-by-step walkthrough, see the community forum guide: How to Enable Centmin Mod Nginx HTTPS HTTP/3 QUIC Support.

Firewall: UDP Port 443

Regular HTTPS uses TCP port 443. HTTP/3 additionally uses UDP port 443. If your firewall blocks UDP traffic on port 443, HTTP/3 connections will silently fail and browsers will fall back to HTTP/2.

For non-CSF firewall setups, manually open UDP port 443:

Verifying HTTP/3 Is Working

After completing the steps above, verify that HTTP/3 is properly configured.

Step 1: Check Nginx compilation — Confirm the HTTP/3 module was compiled into Nginx:

If you see --with-http_v3_module in the output, HTTP/3 support is compiled in.

Step 2: Test from command line — Use curl to make an HTTP/3 request (requires curl 7.88+ with HTTP/3 support):

Look for HTTP/3 200 in the response. If you see HTTP/2 200 instead, HTTP/3 is not being used — check your vhost config and firewall.

Step 3: Browser verification — In Chrome, open DevTools (F12) → Network tab → right-click the column headers → enable “Protocol”. Reload your page — HTTP/3 connections show as h3.

Enabled Modules (Default)

These modules are compiled and enabled by default in every Centmin Mod Nginx build:

Disabled/Optional Modules

These modules can be enabled via /etc/centminmod/custom_config.inc before running centmin.sh menu option 4 to recompile Nginx, or before initial Centmin Mod installation:

GeoIP2 Lite Module

The GeoIP2 module (ngx_http_geoip2_module) allows Nginx to use MaxMind GeoLite2 databases for country, city, and ASN lookups based on client IP. This enables geo-based access control, content localization, and analytics directly at the web server level. To enable GeoIP2, set NGINX_GEOIPTWOLITE='y' in /etc/centminmod/custom_config.inc, recompile Nginx via menu option 4, GeoLite2 databases are downloaded automatically from Centmin Mod's own mirror — no MaxMind account is needed. Optionally, you can set MM_LICENSE_KEY for direct MaxMind downloads.

Enabling the Module

Add the following to /etc/centminmod/custom_config.inc and then recompile Nginx via menu option 4:

# Add to /etc/centminmod/custom_config.inc
NGINX_GEOIPTWOLITE='y'
NGXDYNAMIC_GEOIPTWOLITE='y'

# MaxMind license key is OPTIONAL — Centmin Mod downloads GeoLite2
# databases from its own mirror by default (no account needed).
# Only set MM_LICENSE_KEY if you prefer direct MaxMind downloads:
# MM_LICENSE_KEY='your_maxmind_license_key_here'

Setting NGXDYNAMIC_GEOIPTWOLITE='y' compiles the module as a dynamic (loadable) module. Both variables default to 'n' (disabled). Note: A MaxMind license key (MM_LICENSE_KEY) is optional. By default, Centmin Mod downloads GeoLite2 databases from its own mirror — no MaxMind account or license key is needed. If you prefer direct MaxMind downloads, you can optionally set your own free MaxMind license key in /etc/centminmod/custom_config.inc (see MaxMind License Key section below).

MaxMind License Key (Optional)

By default, Centmin Mod downloads GeoLite2 databases from its own mirror — no MaxMind account or license key is needed. If you prefer direct MaxMind downloads, you can optionally set your own free MaxMind license key in /etc/centminmod/custom_config.inc:

MM_LICENSE_KEY='your_maxmind_license_key_here'

Database Paths

GeoLite2 databases are stored in /usr/share/GeoIP/ and include GeoLite2-Country, GeoLite2-City, and GeoLite2-ASN databases.

Nginx Configuration

After enabling and recompiling, configure GeoIP2 in your Nginx config:

# In nginx.conf http{} block
geoip2 /usr/share/GeoIP/GeoLite2-Country.mmdb {
    $geoip2_country_code country iso_code;
    $geoip2_country_name country names en;
}

geoip2 /usr/share/GeoIP/GeoLite2-City.mmdb {
    $geoip2_city_name city names en;
    $geoip2_region_name subdivisions 0 names en;
}

# Block specific countries in a server{} block
if ($geoip2_country_code = "XX") {
    return 403;
}

PHP Integration

Pass GeoIP2 data to PHP via fastcgi_param directives in your Nginx vhost config:

# In your vhost PHP location block
fastcgi_param GEOIP_COUNTRY_CODE $geoip2_country_code;
fastcgi_param GEOIP_COUNTRY_NAME $geoip2_country_name;
fastcgi_param GEOIP_CITY_NAME $geoip2_city_name;

These values are then accessible in PHP via $_SERVER['GEOIP_COUNTRY_CODE'], etc.

GeoIP2 Automatic Database Updates via Cron

When the GeoIP2 module is enabled, Centmin Mod automatically installs a cron job (tools/geoip2db-update.sh) that runs weekly on Thursdays at 2:20 AM to download updated MaxMind GeoLite2 databases (GeoLite2-Country, GeoLite2-City, and GeoLite2-ASN) to /usr/share/GeoIP/. This ensures your MaxMind geolocation data stays current without manual intervention.

For more details and discussion, see the community forum thread.

Post-Quantum Key Exchange (PQ KEX)

Post-quantum key exchange protects the TLS handshake against future cryptographically-relevant quantum computers. Today’s asymmetric key exchange algorithms (like ECDH/X25519) could be broken by a sufficiently powerful quantum computer, enabling “harvest now, decrypt later” attacks where adversaries record encrypted traffic today and decrypt it once quantum hardware matures. Centmin Mod Nginx supports hybrid PQ KEX algorithms — X25519MLKEM768 and X25519Kyber768Draft00 — which combine classical X25519 with a post-quantum algorithm so the connection remains secure even if one component is broken. Cloudflare already supports PQ KEX at their edge; enabling it on the origin ensures the full Cloudflare ↔ origin path is post-quantum safe. See also: Centmin Mod PQ KEX guide, post-quantum for all, and state of PQ internet 2025.

Requirements

• TLS 1.3 must be enabled (default in Centmin Mod)
• BoringSSL (BORINGSSL_SWITCH='y') — all supported EL versions (EL7/EL8/EL9/EL10)
• AWS-LC (AWS_LC_SWITCH='y') — EL8/EL9/EL10 only, requires Nginx 1.27.0+
• Set the variable in /etc/centminmod/custom_config.inc, then rebuild Nginx via centmin.sh menu option 4, or set before initial Centmin Mod installation

Step 1 — Enable BoringSSL or AWS-LC

Set one of the following in /etc/centminmod/custom_config.inc before running centmin.sh menu option 4 to recompile Nginx, or before initial Centmin Mod installation (they are mutually exclusive):

Step 2 — Configure ssl_ecdh_curve

Add to the http {} block in /usr/local/nginx/conf/nginx.conf (or per virtual host):

Step 3 — Cloudflare Origin Opt-In (Optional)

If your site is behind Cloudflare, opt the zone into post-quantum encryption to the origin via the Cloudflare API:

Valid values: supported (attempt PQ, fall back), preferred (strongly prefer PQ), off.

Step 4 — Verify

After rebuilding Nginx via Menu 4, confirm the SSL library is active:

The output will show built with BoringSSL or built with AWS-LC confirming PQ KEX capability.

Crypto Library Support Matrix

Centmin Mod supports six different SSL/crypto libraries for Nginx, each offering different trade-offs. Multiple options exist because mainstream OpenSSL has historically lagged behind on HTTP/3 QUIC support, post-quantum key exchange, and performance optimizations. Having alternatives also provides security resilience — if one library has a vulnerability and patches are slow, you can quickly switch to another to reduce your exposure window.

Library Overview

Set the desired variable in /etc/centminmod/custom_config.inc before running centmin.sh menu option 4 to recompile Nginx, or before initial Centmin Mod installation.

OS & Branch Compatibility

Not every library is available on every OS or branch. EL10 support requires branch 141.00beta01.

Module Compatibility

Some crypto libraries disable certain Nginx modules. Check this table before switching.

Strengths & Trade-offs

Quick Reference

Add one of these lines to /etc/centminmod/custom_config.inc before running centmin.sh menu option 4 to rebuild Nginx, or before initial Centmin Mod installation:

BoringSSL TLS 1.3

BoringSSL is Google’s fork of OpenSSL that provides TLS 1.3 support with post-quantum key exchange. To enable BoringSSL, set BORINGSSL_SWITCH='y' in /etc/centminmod/custom_config.inc.

Then update Centmin Mod and recompile Nginx:

BoringSSL requires Nginx 1.15.3 or newer (the current Centmin Mod default of Nginx 1.29.6 meets this requirement).

To switch back to OpenSSL, set BORINGSSL_SWITCH='n' in /etc/centminmod/custom_config.inc and recompile Nginx via centmin.sh menu option 4.

For more details, see the forum discussion.

OpenResty Lua Module

Centmin Mod includes the OpenResty Lua Nginx module as a dynamic module (NGINX_OPENRESTY='y'). This is enabled by default. To override, set the variable in /etc/centminmod/custom_config.inc before running centmin.sh menu option 4 or before initial Centmin Mod installation. This embeds LuaJIT into Nginx for high-performance scripting directly in your Nginx configuration.

Companion OpenResty modules included:

• set-misc-nginx-module — Extended set directives (base64, hashing, random)
• echo-nginx-module — Shell-style echo, sleep, time in configs
• ngx_devel_kit — Development kit for third-party modules

Dynamic modules are loaded in /usr/local/nginx/conf/dynamic-modules.conf and can be individually enabled or disabled.

Brotli Compression

Brotli compression is compiled as a dynamic module (NGXDYNAMIC_BROTLI='y'), enabled by default. To override, set the variable in /etc/centminmod/custom_config.inc before running centmin.sh menu option 4 or before initial Centmin Mod installation. It provides 15-25% better compression than gzip for text-based content. It supports both on-the-fly compression and serving pre-compressed .br files.

For image optimization, Nginx can also conditionally serve WebP format images to supported browsers, providing up to 80% file size reduction over JPG/PNG.

HTTP Concat Module

The nginx-http-concat module (by Alibaba) concatenates multiple CSS or JavaScript files into a single response, reducing HTTP requests. It is disabled by default.

Enable it with NGINX_HTTPCONCAT='y' in /etc/centminmod/custom_config.inc before running centmin.sh menu option 4 to recompile Nginx, or before initial Centmin Mod installation.

Usage Example

Request multiple files in one URL:

Nginx Upgrade / Downgrade (Menu 4)

Use centmin.sh menu option 4 to upgrade or downgrade Nginx after Centmin Mod is already installed. This recompiles Nginx from source with all your configured modules. Menu option 4 is for post-install upgrades only — for the initial installation, Centmin Mod installs Nginx 1.29.6 by default, or you can set NGINX_VERSION in /etc/centminmod/custom_config.inc before running the installer to use a different version.

Editing Configs the Right Way

Always set configuration variables in /etc/centminmod/custom_config.inc (shortcut: customconfig) rather than editing centmin.sh directly. This persists your settings across Centmin Mod updates.

Auto-Backup on Upgrade

Before each Nginx upgrade, Centmin Mod automatically backs up your Nginx directory to /usr/local/nginxbackup. This allows you to restore your previous Nginx installation if needed.

Persistent Config File Management (Menu 7)

Menu option 7 manages persistent configuration files. Additionally, the Nginx VTS (Virtual Host Traffic Status) module can be optionally enabled to provide real-time traffic statistics per virtual host including request counts, response times, and bandwidth usage.

Enable VTS with NGINX_VHOSTSTATS='y' and recompile via Menu 4.

Access & Error Logs

Nginx log files in Centmin Mod include the Centmin Mod main server logs, default virtual host logs, and per-vhost (per-domain) logs:

Centmin Mod Main Nginx Log Paths

• /usr/local/nginx/logs/error.log — Centmin Mod main Nginx error log (compiled-in default)
• /usr/local/nginx/logs/access.log — Centmin Mod main Nginx access log (compiled-in default)

Default Virtual Host & Per-Domain Log Paths

• /var/log/nginx/error.log — Default virtual host error log
• /var/log/nginx/access.log — Default virtual host access log
• /home/nginx/domains/domain.com/log/access.log — Per-vhost access log
• /home/nginx/domains/domain.com/log/error.log — Per-vhost error log

Log rotation is handled automatically via logrotate with daily rotation and 10 days of retention.

JSON-Based Access Logging

Centmin Mod supports JSON-formatted access logs for easier parsing and analysis. The log_format main_json format is already defined in the base /usr/local/nginx/conf/nginx.conf template — you do not need to add it manually.

To enable JSON logging for a vhost, add the following access_log directive to your vhost configuration file:

You can parse JSON logs with jq (pre-installed by Centmin Mod):

Centmin Mod’s logrotate configuration automatically handles JSON log files alongside the standard access and error logs.

For more details, see the forum discussion.

Cloudflare Custom Logging in nginx.conf http{} Block

When running behind Cloudflare, you can define custom Nginx log formats in /usr/local/nginx/conf/nginx.conf inside the http{} block to capture Cloudflare-specific headers like CF-RAY, CF-Connecting-IP, and SSL/TLS details. Centmin Mod’s built-in main_json log format already includes CF headers ($http_cf_ray, $http_cf_worker, $http_cf_request_id, $http_cf_railgun), but you can also create focused custom formats for specific analysis needs.

# Cloudflare custom log format with CF-RAY, real IP, and SSL info
log_format cf_custom '$http_cf_connecting_ip - $remote_user [$time_local] '
                     '"$request" $status $body_bytes_sent '
                     '"$http_referer" "$http_user_agent" '
                     '$http_cf_ray $http_cf_ipcountry $ssl_protocol $ssl_cipher';

# Extended format with request timing
log_format cf_custom2 '$http_cf_connecting_ip [$time_local] "$request" '
                      '$status $body_bytes_sent $request_time '
                      '$http_cf_ray $ssl_protocol/$ssl_cipher';

# Minimal format for high-traffic analysis
log_format cf_custom3 '$http_cf_connecting_ip $http_cf_ipcountry '
                      '$status $request_time "$request_uri"';

Then use the format in a vhost or server block:

access_log /home/nginx/domains/domain.com/log/cf_access.log cf_custom;

Analyzing SSL/TLS Protocol Versions from Cloudflare Logs

Use awk to extract and analyze $ssl_protocol and $ssl_cipher fields from the cf_custom log format to identify TLS version distribution across your traffic:

# Count requests by country (using cf_custom format)
awk '{print $NF}' /home/nginx/domains/domain.com/log/cf_access.log | sort | uniq -c | sort -rn

# Analyze SSL/TLS protocol versions
awk '{print $(NF-1)}' /home/nginx/domains/domain.com/log/cf_access.log | sort | uniq -c | sort -rn

# Find slow requests (request_time > 1s) using cf_custom2 format
awk '$6 > 1.0 {print $0}' /home/nginx/domains/domain.com/log/cf_access.log

For processing compressed (rotated) log files, see Processing Compressed Logs.

For more details and discussion, see the community forum thread.

Configuration Error Checking

Always test your Nginx configuration before reloading:

Password Protect a Directory or File

Centmin Mod includes the htpasswd.sh tool at /usr/local/src/centminmod/tools/htpasswd.sh for creating HTTP Basic Authentication password files.

Create a password file with a username and password:

Then add an auth_basic block to your Nginx vhost configuration to protect a directory:

To protect a specific file (for example, a WordPress login page):

After making changes, test and restart Nginx:

For more details, see the forum discussion.

Adding/Enabling Modules

To enable or disable Nginx modules:

1. Edit /etc/centminmod/custom_config.inc
2. Set the module variable to 'y' (enable) or 'n' (disable)
3. Run centmin.sh menu option 4 to recompile Nginx, or set variables before initial Centmin Mod installation

Key Configuration Files