Nginx


Last modified: November 14, 2019

Overview

This document explains how to install Nginx on a server that runs cPanel & WHM and EasyApache 4. Nginx is an open source web server that also provides a reverse proxy, load balancing, and caching. It functions very differently from Apache®. Nginx does not serve dynamic content unless you pass it through a proxy.

Warning:
Nginx is experimental. You must install the Experimental Repository to use it.

Requirements

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

  • Run EasyApache 4.

  • Install the Experimental Repository. Use the following command to install this repository:

    yum install ea4-experimental

  • Possess root user access to the server.

  • Use PHP-FPM as the server’s PHP handler.

Compatibility

Nginx takes the place of Apache as the primary web server. The installation will move Apache away from its default ports in favor of Nginx.

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

Note:
You can still use Apache to serve dynamic content, but must proxy your requests to the server.

Install or uninstall Nginx

Install

Note:
If the Experimental Repository does not already exist on your server, install it with the following command:
yum install ea4-experimental

To install Nginx, run the following command on the command line:

yum --enablerepo=EA4-experimental install ea-nginx

Uninstall

To uninstall Nginx, run the following command on the command line:

yum erase ea-nginx

The Nginx installation

When you install cPanel & WHM’s version of Nginx, the installation process will change your server’s Apache installation to use different ports.

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

The following features will work with Nginx without any further action by the user:

  • Static content.

    Note:
    You must proxy any dynamic content to Apache.

  • The MultiPHP system.

  • WordPress® installed via WordPress Manager.

    Warning:
    • Installations of WordPress outside of WordPress Manager will not support Pretty Permalinks. For more information, read WordPress’ Pretty Permalinks documentation.

    • If you do not wish to manage your WordPress site through WordPress Manager, read the WordPress does not support Pretty Permalinks section below.

  • Mailman.

  • AutoSSL.

  • Proxy subdomains and redirects.

    Important:
    The MultiPHP system and Wordpress will only work if you use PHP-FPM.

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.

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.

User configuration

Note:

In the following examples, username represents the username, and fqdn 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/fqdn/

To use the same .conf file in multiple locations, place your file in the following directory:

/etc/nginx/conf.d/server-includes-optional/
Note:
Make certain that you also reference your .conf file with an include directive in the file that you want to use it in.

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. You must proxy any applications that are not static to Apache.

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

Log Files

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

  • /var/log/nginx/domains/domainname
  • /var/log/nginx/domains/domainname-bytes_log

Nginx uses the cPanel & WHM default Apache log formats. It will not recognize any custom Apache log formats

Note:
Nginx uses the same server block for both SSL and non-SSL requests, so -ssl log files do not exist.

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 CentOS 6 or CentOS 7 restart commands to restart Nginx, you must use the reload option to ensure a graceful restart. Use the appropriate command for your operating system version:

  • CentOS 6 — /etc/init.d/nginx reload

  • CentOS 7 — systemctl reload nginx.service

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

Configure a user

In cPanel & WHM version 80 and later, the system integrates Nginx into your user and domain changes, with the following exceptions:

  • PHP-FPM Hostname Changes
  • Piped Log Configuration
  • Apache log style

The system integrates these changes in cPanel & WHM version 86 and later.

Note:
It may take your Nginx configuration several minutes to update if you make changes to your PHP version or PHP-FPM configuration, enable or disable PHP-FPM, or add WordPress.

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

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.

Warning:
  • When you use Nginx, your ModSecurity™ rules will not apply.

  • Any restrictions set in an .htaccess file will not apply. For example, if you password-protected a directory, the protection will not work.

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

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/conf.d/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

Installations of WordPress outside of WordPress Manager will not support Pretty Permalinks.

To resolve this issue, you must perform one of the following actions:

  • Manage your WordPress site through WordPress Manager.

  • Add the following information to your Nginx configuration file, where php73 represents the version of PHP your server runs and 1ed179754201ac2644e8c70140bacb23c7786484 represents the PHP-FPM socket though which WordPress runs:

Note:
  • To obtain the correct PHP-FPM socket, run the following command where username represents the username:

    awk -F ':' '/fastcgi_pass unix/ {gsub(/;/,""); print $2}' /etc/nginx/conf.d/users/username.conf

  • Be sure to follow the instructions in the Configure a user section of this document so Nginx does not overwrite your changes.

1
2
3
4
5
6
7
8
location /wordpress {
     try_files $uri $uri/ /wordpress/index.php?$args;
      location ~ \.php7?$ {
      include conf.d/includes-optional/cpanel-fastcgi.conf;
      fastcgi_pass unix:/opt/cpanel/ea-php73/root/usr/var/run/php-fpm/1ed179754201ac2644e8c70140bacb23c7786484.sock;
      error_page 502 503 /FPM_50x.html;
  }
}

Additional Documentation