Last modified: August 21, 2024

Overview

This document explains how to install NGINX with Reverse Proxy on a server that runs cPanel & WHM and EasyApache 4. This version of NGINX uses caching in order to serve content more quickly.

NGINX is an open source web server that also provides a reverse proxy, load balancing, and caching. cPanel & WHM’s NGINX with Reverse Proxy passes dynamic content through a proxy to Apache®.

Requirements

To install NGINX on your server, you must meet the following requirements:

• Run EasyApache 4.
• Possess root user access to the server.

Compatibility

NGINX takes the place of Apache as the primary web server. The installation will change Apache’s default ports and assign those port numbers to NGINX.

For more information, read the NGINX configuration changes section below.

Limitations

cPanel & WHM’s implementation of NGINX has the following limitations:

• If one of your domains matches a proxy domain, the system will warn you that it will ignore conflicting duplicate entries. This conflict may result in unexpected behavior.
• If you use NGINX and ModSecurity® 2, your ModSecurity rules only apply when NGINX proxies the request to Apache.
• NGINX redirects any non-SSL IPv6 requests to use SSL. This ensures that any IPv6-only service subdomains will work correctly. If your client will not accept the hostname’s security certificate, we recommend that you use the subdomain’s fully-qualified domain name instead.
• For security reasons, NGINX will not serve any file with a name starting with .ht.
• cPanel’s Optimize Website interface (cPanel » Home » Software » Optimize Website) will not affect NGINX.
• If you create a custom NGINX configuration that uses the NGINX alias directive, make certain that your path’s location ends with a trailing slash (/). If your path does not end with a /, then your path is vulnerable to a path traversal exploit. For more information, read the NGINX Security Advisories documentation.

Install or uninstall NGINX

Install

To install NGINX, use WHM’s NGINX Manager interface (WHM » Home » Software » NGINX Manager).

You can also use the EasyApache 4 interface, or run the following command on the command line as the root user:

Uninstall

To uninstall NGINX, use WHM’s NGINX Manager interface (WHM » Home » Software » NGINX Manager).

You can also run the following command on the command line as the root user:

The NGINX installation

When you install cPanel & WHM’s version of NGINX with Reverse Proxy, the installation process will change your server’s Apache installation to use different ports. NGINX will proxy all requests to Apache.

NGINX also installs the mod_remoteip Apache module if it does not already exist. This module ensures that the system properly sets the REMOTE_ADDR variable to the correct IP address when requests are proxied to Apache. For more information, read the Apache mod_remoteip section below.

NGINX configuration changes

When you install NGINX on your server, the installation process makes several changes to your system. Most notably, the installation configures Apache to no longer act as the primary web server.

Caching

NGINX reverse proxies to Apache and caches all requests by default.

NGINX caches data on a per-user basis. The cache file is stored in the following location, where type represents the type of caching, and username represents the username:

/var/cache/ea-nginx/proxy/username

NGINX with Reverse Proxy uses the type proxy for the proxy_pass directive. The cache directories use 700 permissions, restricted to the nobody and root users.

Your application’s requests for dynamic content should include cache control headers. If they do not, the server may return cached responses that do not apply to the user.

To correct this issue, perform one of the following actions:

• Disable caching for the user in WHM’s NGINX Manager interface (WHM » Home » Software » NGINX Manager).
• Modify your web application to use the appropriate headers so NGINX does not cache the request.

Custom cache keys

You can set your NGINX cache to generate separate caches for different conditions. For example, you may want to cache mobile and non-mobile requests separately.

To configure your cache to use separate caches in varying conditions, set the $CACHE_KEY_PREFIX in the /etc/nginx/conf.d/includes-optional/set-CACHE_KEY_PREFIX.conf file. We include this file by default, with the option to cache mobile requests separately commented out.

For more information about proxies in NGINX, read the NGINX Proxy documentation.

Use htaccess to manage caching

You can also use your .htaccess files to manage caching in NGINX. If you use this method, your .htaccess file will set the header in your requests to handle caching for any requests your application does not set.

Your applications should set appropriate headers to ensure that sensitive data is not cached. If you cannot update your application to send appropriate headers, then you can use your .htaccess file. The entry in your .htaccess file might resemble the following example:

1
2
3
4
5
6
7
8

# Broken-app does not set proper headers and sends private data. This needs to be updated in the application and this section removed.
<If "%{REQUEST_URI} =~ m#/payment-methods/#">
    <IfModule mod_headers.c>
        Header set Pragma "no-cache"
        Header set Cache-Control "max-age=0, no-cache, no-store, must-revalidate"
        Header set Expires "Thu, 1 Jan 1970 00:00:00 GMT"
    </IfModule>
</If>

Add the following to your .htaccess file to enable caching for common static files:

1
2
3

<filesMatch ".(ico|pdf|flv|jpg|jpeg|png|gif|js|css|swf)$">
Header set Cache-Control "max-age=3600, public"
</filesMatch>

Configuration files

The system creates the /etc/nginx/conf.d/ea-nginx.conf configuration file. NGINX uses .conf configuration files for direct configuration.

It also creates the following files when you install the ea-nginx package:

• /etc/nginx/ea-nginx/settings.json
• /etc/nginx/ea-nginx/cache.json

The ea-nginx script uses files that end in .json to specify the values when it generates configuration files.

Configuration settings

You can set the following directives for NGINX in WHM’s Global Configuration interface (WHM » Home » Service Configuration » Apache Configuration » Global Configuration). The following values in the Global Configuration interface correspond to the following directives:

• Keep-Alive — This directive corresponds to the keepalive directive. If you set this value to On, NGINX uses a value of 32. If you want to use a different value, set the keepalive value to a valid number in the /etc/nginx/ea-nginx/settings.json file.
• Keep-Alive Timeout — This directive corresponds to the keepalive_timeout directive. NGINX only uses the value set in WHM’s Global Configuration interface.
• Max Keep-Alive Requests — This directive corresponds to the keepalive_requests directive. NGINX only uses the value set in WHM’s Global Configuration interface.
  Note:

  If you set this value to Unlimited in the Global Configuration interface, then NGINX uses a value of 1000.

Custom configurations

To customize your NGINX configuration before you install the ea-nginx package, you can create the following files:

• /var/nginx/ea-nginx/settings.json
• /var/nginx/ea-nginx/cache.json

If these files exist when you install NGINX or rebuild your NGINX configuration, the system will copy them to the /etc/nginx/ea-nginx/settings.json and /etc/nginx/ea-nginx/cache.json files respectively, then delete the original files. For more information, read the Configuration settings section.

We also support the following directives in the /var/nginx/ea-nginx/settings.json file:

• keepalive_time
  Note:

  No Apache equivalent exists for the keepalive_time value.
• worker_shutdown_timeout
• worker_processes

Server blocks

If you want to customize the server blocks for NGINX, create an include file that ends in .conf in the appropriate location. A server block is the same thing as a virtual host in Apache.

Each server block will include the .conf files in the /etc/nginx/conf.d/server-includes/ directory.

For more information about server blocks, including examples, read NGINX’s Server Block Examples documentation.

Global configuration

Place any global .conf files that you create in the /etc/nginx/conf.d/ directory.

If you want to adjust every server block on your server, create your .conf file in the /etc/nginx/conf.d/server-includes/ directory.

User configuration

To customize every server block that a user owns, create your .conf file in following directory:

/etc/nginx/conf.d/users/username

To customize a specific server block for a specific domain, create your .conf file in the following directory:

/etc/nginx/conf.d/users/username/domainname/

Apache configuration

The NGINX installation makes the following changes to your Apache configuration:

• Changes the Apache port to the first available port under 1024. This will usually be port 81.
• Changes the Apache SSL port to the first available port under 1024. This will usually be port 444.
  Note:

  Your Apache ports will only change if your configuration uses the default ports 80 and 443. The installation ignores custom port numbers.
• Adds the following to the /etc/nginx/conf.d/ea-nginx.conf file:

  1 2 3 4 5 6

  map $host $CPANEL_APACHE_PROXY_IP { default 127.0.0.1; } map $host $CPANEL_APACHE_PROXY_PORT { default 81; }

Apache mod_remoteip

The NGINX installation installs the Apache mod_remoteip module if it does not already exist.

When NGINX installs this package, it edits the proxy configuration files. This ensures that the system properly sets the REMOTE_ADDR variable to the correct IP address when requests are proxied to Apache.

This allows NGINX to securely proxy to Apache and prevents spoofed IP addresses via mod_remoteip.

• If you customized your /var/cpanel/templates/apache2_4/ea4_main.local file, then you must update the file based on the contents of the /var/cpanel/templates/apache2_4/ea4_main.default file.

• If you already installed the mod_remoteip module, we recommend that you remove the following entries from your include files:

  • RemoteIPHeader
  • RemoteIPInternalProxy

  This ensures that your configuration uses the provided secure settings.

File access

NGINX does not serve files that start with .ht by default. There may be other files that you want to restrict access to.

The easiest solution is to not include restricted-access files in the document root. However, if this is not possible, you can also explicitly restrict access to files.

For example, if you serve your website from a git repository, you may want to prevent access to the site’s .git directory. To do this, create a .conf file in the appropriate location and add the following commands to your file:

1
2
3
4
5
6

location ~ /\.git {
       deny all;
       log_not_found off;
       access_log off;
       return 404;
   }  

After you save the file, reload your server to activate the configuration change.

For more information, read the NGINX Location Priority documentation.

CloudFlare®

The NGINX installation configures the system to work properly with CloudFlare.

The system saves the CloudFlare configuration to the following location:

/etc/nginx/conf.d/includes-optional/cloudflare.conf

If your secure connections don’t appear in the SSL log, you can change the SSL settings in CloudFlare.

Log Files

NGINX rotates logs with the logrotate utility. This means that WHM’s cPanel Log Rotation Configuration interface (WHM » Home » Service Configuration » cPanel Log Rotation Configuration) will not affect the NGINX log rotation. This activity will register in your user stats and bandwidth programs.

NGINX uses the cPanel & WHM default Apache log formats. It will not recognize any custom Apache log formats. You cannot manage NGINX logs in any interfaces that specifically displays Apache logs, such as WHM’s Log Rotation interface (WHM » Home » Service Configuration » Log Rotation).

Apache does not log any requests that NGINX proxies to it. These requests are only logged by NGINX.

NGINX logs traffic for the www subdomain to the same location as non-www subdomains, which duplicates the Apache behavior. For example, it will log requests for www.example.com and example.com to the /var/log/nginx/domains/example.com file.

NGINX uses the same server block for both SSL and non-SSL requests. However, it handles requests differently depending on if you use piped logging or not.

Piped logging

NGINX saves its log files to the following locations, where domainname represents the domain name:

• SSL — /var/log/nginx/domains/domainname-ssl_log
• Non-SSL — /var/log/nginx/domains/domainname
• Bandwidth — /var/log/nginx/domains/domainname-bytes_log

NGINX also logs requests to the following location:

/var/log/nginx/access.log

Regular logging

Without piped logging, both SSL and non-SSL requests save to the same location. NGINX saves its log files to the following locations, where domainname represents the domain name:

• SSL and non-SSL — /var/log/nginx/domains/domainname
  Note:

  These files will also contain an extra column at the beginning, in domainname:port format.
• Bandwidth — /var/log/nginx/domains/domainname-bytes_log

Run NGINX

To stop or restart NGINX, use the /usr/local/cpanel/scripts/restartsrv_nginx script.

We strongly recommend that you only use the cPanel script or WHM’s Service Manager interface (WHM » Home » Service Configuration » Service Manager) to restart NGINX.

For more information, read our How to Restart Services documentation.

Configure a user

The system integrates NGINX into your user and domain changes.

The system uses the /usr/local/cpanel/scripts/ea-nginx script to make these changes. You do not need to run this script.

The system creates the .conf file in the following location, where username represents the username:

/etc/nginx/conf.d/users/username.conf

Configure an application

Use cPanel’s Application Manager interface (Home » cPanel » Software » Application Manager) to configure applications.

NGINX-specific packages

We provide some additional packages that you can use with NGINX. These packages provide functionality that may otherwise be missing in the installation.

Compression

We provide the gzip and Brotli packages to enable compression on NGINX. If you install one of these packages, it will enable that compression globally.

If you use compression with SSL/TLS requests, your compressed responses may be vulnerable to BREACH attacks. To lower the risk of this type of attack, you can perform one of the following actions:

1. Do not send sensitive data in your HTTP responses.
2. Limit your responses to only use secure samesite cookies.

Brotli

To use Brotli, install the ea-nginx-brotli package in the Additional Packages section of WHM’s EasyApache 4 interface (WHM » Home » Software » EasyApache 4)..

You can use the /etc/nginx/conf.d/brotli.conf configuration file to configure your Brotli installation. For more information about configuring Brotli, read the NGINX Brotli module documentation.

gzip

To use gzip, install the ea-nginx-gzip package in the Additional Packages section of WHM’s EasyApache 4 interface (WHM » Home » Software » EasyApache 4).

You can use the /etc/nginx/conf.d/gzip.conf configuration file to configure your gzip installation. For more information about configuring gzip, read the NGINX gzip module documentation.

HTTP2

To use HTTP/2 with NGINX, you must install the ea-nginx-http2 package. You can install this package in the Additional Packages section of WHM’s EasyApache 4 interface (WHM » Home » Software » EasyApache 4).

When you install the ea-nginx-http2 package, the system creates the /etc/nginx/conf.d/http2.conf file. This is a comment-only file that you can use to set your system’s HTTP/2 configuration. NGINX only supports HTTP/2 via SSL. NGINX terminates the protocol when it sends a proxy request to Apache that uses HTTP/2. NGINX uses HTTP 1.1 to communicate with Apache.

NGINX JavaScript Module (NJS)

The NGINX JavaScript module (NJS) allows you to use NGINX’s JavaScript-based scripting language with your NGINX server. To use NJS, install the ea-nginx-njs package in the Additional Packages section of WHM’s EasyApache 4 interface (WHM » Home » Software » EasyApache 4).

You can use the /etc/nginx/conf.d/njs.conf configuration file to configure your NJS installation.

For more information, read the NGINX NJS documentation.

Third-party integration

Third-party integrators can use the following information to determine if NGINX caching is active. You can only use caching if you install the ea-nginx package. We also display the caching status in the NGINX Caching section of the cPanel Interface.

If the /etc/nginx/ea-nginx/cache.json file exists, you can determine if caching is enabled or disabled based on the following information:

• If the enabled key exists in the following file, its value determines if NGINX caching is enabled. In this example, user represents the username:

  /var/cpanel/userdata/user/nginx-cache.json

• If the enabled key exists in the following global configuration file, its value determines if NGINX caching is enabled. In this example, user represents the username:

  /etc/nginx/ea-nginx/cache.json

• If the enabled key does not exist in either file, then caching is enabled by default.

If the /etc/nginx/ea-nginx/cache.json file does not exist, then ea-nginx is not installed on the server.

If the /etc/nginx/ea-nginx/enable.standalone file exists, the ea-nginx-standalone package is installed, and caching is not enabled on the server.

Troubleshooting

Could not build proxy_headers hash

You may receive an error that resembles the following message:

1

nginx: [emerg] could not build proxy_headers_hash, you should increase proxy_headers_hash_bucket_size

If you receive this error message, one of your .conf files contains a proxy_set_header directive that sets a very long header name. To correct this error, add the following directive to the .conf file that contains the long proxy_set_header directive, where number represents a header length:

proxy_headers_hash_bucket_size number;

You must add this directive immediately before the long proxy_set_header directive.

NGINX will not restart

If you used the nginx command to start NGINX, then the /usr/local/cpanel/scripts/restartsrv_nginx and systemctl restart nginx.service commands will not work. To correct this, perform the following steps:

1. Stop the service with the /usr/sbin/nginx -s stop command.

2. Restart NGINX with one of the following commands:

   • /usr/local/cpanel/scripts/restartsrv_nginx start
   • systemctl start nginx.service
   • /etc/init.d/nginx start