NGINX® Standalone

Overview

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.

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.

Install or uninstall NGINX

Install

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.

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.

• 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

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.

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. 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 (Home >> cPanel >> Domains >> Redirects) interface. 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 (Home >> cPanel >> Domains >> Domains) interface.
• 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.

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:

  • Do not use both of these files in your symlinks. This will create an infinite loop.
  • You must run the /usr/local/cpanel/scripts/ea-nginx script command after you create your .conf file.

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

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

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

In cPanel & WHM version 86 and later, the system integrates these 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 version of cPanel & WHM, you must run the /usr/local/cpanel/scripts/ea-nginx script to update your configuration and restart the server.

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.

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.

Can’t use Pretty Permalinks with WordPress

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:

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