1. cPanel & WHM Documentation
  2. cPanel Knowledge Base
  3. Experimental Software
  4. NGINX® Standalone
nginx apache server whmadvanced

NGINX® Standalone

Last modified: February 19, 2024

Overview

Note:

This document refers to NGINX® functionality when you install the ea-nginx-standalone package. This was our original version of NGINX and we renamed that package. For information about the newer, updated ea-nginx package, read our NGINX with Reverse Proxy documentation.

This document explains how to install NGINX Standalone 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.

Experimental:

NGINX Standalone 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.
  • Install the ea-ruby27-mod_passenger Apache module. When you install the ea-nginx-standalone module, the system will install this module and other necessary Ruby modules if they don’t already exist.
    Note:
    • If your system runs CentO6, install the ea-ruby24-mod_passenger Apache module.
    • Phusion Passenger® functions the same in both NGINX and Apache.

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-standalone

Uninstall

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

yum erase ea-nginx-standalone

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.

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

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

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

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

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.

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

Redirects

NGINX supports proxy subdomains and redirects. To create a redirect, use cPanel’s Redirects interface (Home » cPanel » Domains » Redirects). These redirects differ from the Apache redirect behavior in the following ways:

  • Redirects apply to the whole server block, not the exact fully qualified domain name (FQDN). If you set a redirect for one domain, it will also effect any other FQDN in the block.
  • Redirects apply to both the www and any non-www subdomains, regardless of the behavior in Apache. You can change this behavior with include files.
  • Redirects do not change HTTP requests to HTTPS requests. To enable this behavior, use the Force HTTPS Redirect option in cPanel’s Domains interface (Home » cPanel » Domains » Domains).
  • Redirects that point to an index.html file will also redirect the domain name both with and without a trailing slash. For example, NGINX will redirect both example.com and example.com/.
    Note:

    If the redirect matches another index file first, then it will serve that index file.

  • NGINX only returns the 301 and 302 HTTP status codes.
Note:

You cannot use the Safari® web browser to log in to a service subdomain. Use another browser, or log in with the service’s port URL.

Use include files to change redirect behavior

You can use include files to force NGINX to redirect www domains to non-www domains, and vice versa. You cannot use these include files for parked domains or to redirect HTTP to HTTPS.

To do this, we created the following include files. You can create a symlink that points to one of the following files to alter the redirect behavior:

  • /etc/nginx/conf.d/includes-optional/force-non-www.conf
  • /etc/nginx/conf.d/includes-optional/force-www.conf
Warning:

To set redirect behavior for all of a user’s domains, add the following symlink, where redirect-file represents one of the files above and username represents the user:

ln -s redirect-file /etc/nginx/conf.d/users/username/www-behavior.conf

To set redirect behavior for only specific domains, add the following symlink, where redirect-file represents one of the files above, username represents the user, and domainname represents the domain or subdomain:

ln -s redirect-file /etc/nginx/conf.d/users/username/domainname/www-behavior.conf

For example, to redirect www.sub.example.com to sub.example.com you might run the following commands:

1
2

mkdir -p /etc/nginx/conf.d/users/myuser/sub.example.com
ln -s /etc/nginx/conf.d/includes-optional/force-non-www.conf /etc/nginx/conf.d/users/myuser/sub.example.com/non-www-behavior.conf

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

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

Configure an application

You can use cPanel’s Application Manager interface (Home » cPanel » Software » Application Manager) to configure applications.

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:
  • If you use NGINX and ModSecurity® 2, your ModSecurity rules only apply when NGINX proxies the request to Apache.
  • 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/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

WordPress Multisite

WordPress Multisite does not work with cPanel & WHM servers that use nginx.

Installations of WordPress will not support Pretty Permalinks. To resolve this issue, add the following information to your NGINX configuration file, where php## 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-php##/root/usr/var/run/php-fpm/1ed179754201ac2644e8c70140bacb23c7786484.sock;
      error_page 502 503 /FPM_50x.html;
  }
}

Additional Documentation