NGINX with Reverse Proxy

Valid for versions 96 through the latest version

Version:

94

96


Last modified: July 26, 2021

Overview

Note:
  • This document refers to NGINX® functionality when you install the ea-nginx package in either WHM’s NGINX Manager interface (WHM >> Home >> Software >> NGINX Manager) or WHM’s EasyApache 4 interface (WHM >> Home >> Software >> EasyApache 4).This package is our production version of NGINX. For information about our previous, experimental version of NGINX, now our ea-nginx-standalone package, read our NGINX Standalone documentation.

  • This feature is not currently compatible with The LiteSpeed Web Server.

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.

  • Install the ea-ruby27-mod_passenger Apache module. When you install the ea-nginx package, the system will install this module and other necessary Ruby modules if they don’t already exist.

    Note:
    • If your system runs CentOS 6, install the ea-ruby24-mod_passenger Apache module.
    • Phusion Passenger® functions the same in both NGINX and Apache.

  • Install the mod_remoteip Apache module. This module allows Apache to log the IP address correctly when you use NGINX as a reverse proxy.

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.

Note:

If you do not want to proxy all of your content through Apache, you can use our standalone version of NGINX.

Limitations

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

  • Your requests must use a domain name to send requests to NGINX reverse proxy with caching. IP-address-based requests may result in unexpected behavior.

  • 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.

  • 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 an alias, 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:

yum install ea-nginx

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:

yum erase ea-nginx

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.

Note:

The process will only change your Apache ports if your Apache configuration uses the default ports of 80 and 443.

When you install NGINX, the installation process installs the ea-ruby27-mod_passenger Apache module. This module is required.

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. Because of this, the NGINX installation will create proxies for Mailman and AutoSSL.

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/type/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.

If your application uses GET or HEAD requests for dynamic content and does not include cache control headers, 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.

Configuration files

The system creates the /etc/nginx/conf.d/ea-nginx.conf configuration file.

Custom configurations

Warning:
  • Do not edit any of the files that NGINX owns. Changing these files may result in unexpected behavior.

  • If you create custom configuration files, you may change NGINX behavior in undesired ways. For example, if your custom block matches the PHP block, the server may serve the source code instead of PHP.

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.

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

Note:

Do not use cpanel- as the prefix for any custom files you create.

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.

Note:

Make certain that you also reference your .conf file with an include directive in the file that you want to use it in.

User configuration

Note:

In the following examples, username represents the username, and domainname represents the fully-qualified domain name.

This fully-qualified domain name must be one of the following:

  • The server block’s main domain.

  • The server block’s subdomain for addon domains and their subdomains.

  • The server block’s subdomain for subdomains that are not addon domains.

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;
        }

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 will detect if a domain uses CloudFlare and configure the system to work properly.

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.

Note:
  • The /usr/local/cpanel/scripts/runweblogs script does not process logs for NGINX.
  • The following interfaces do not work with NGINX:
    • cPanel’s Visitors interface (cPanel >> Home >> Metrics >> Visitors)
    • cPanel’s Errors interface (cPanel >> Home >> Metrics >> Errors)
    • cPanel’s Raw Access interface (cPanel >> Home >> Metrics >> Raw Access)

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.

To use the restart commands in CentOS 7 to restart NGINX, you must use the reload option. This option ensures a graceful restart:

systemctl reload nginx.service

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

In cPanel & WHM version 90 and later, you can use cPanel’s Application Manager interface (Home >> cPanel >> Software >> Application Manager) to configure applications.

In previous versions of cPanel & WHM, you must run the /usr/local/cpanel/scripts/ea-nginx script to update your configuration and restart the server.

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, then the ea-nginx package is installed on the server. 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 exists, 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 the server_names_hash

You may receive an error that resembles the following message:

1
2
3
could not build the server_names_hash,
you should increase either server_names_hash_max_size: 512
or server_names_hash_bucket_size: 32

If you receive this error message, increase the value of the following directives in the /etc/nginx/conf.d/ea-nginx.conf and the /etc/nginx/ea-nginx/settings.json files:

  • server_names_hash_max_size

  • server_names_hash_bucket_size

For more information, read the NGINX Server Names documentation.

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

Additional Documentation