NGINX Standalone on cPanel & WHM Servers: Installation and Configuration

Last modified: February 4, 2025

Overview

Note: This document specifically addresses NGINX functionality when the ea-nginx-standalone package is installed. This was our original NGINX version, and the package name has since been updated. For details on the newer ea-nginx package, please refer to our NGINX with Reverse Proxy documentation.

This document provides instructions for installing NGINX Standalone on servers utilizing cPanel & WHM and EasyApache 4. NGINX is an open-source web server that also offers capabilities such as reverse proxy, load balancing, and caching. It operates distinctly from Apache®, and notably, NGINX does not serve dynamic content unless it is passed through a proxy.

Requirements

To successfully install NGINX on your server, the following prerequisites must be met:

• EasyApache 4 must be running.
• The Experimental Repository must be installed. Use the following command to install this repository:

  yum install ea4-experimental

• You must have root user access to the server.
• PHP-FPM must be configured as the server’s PHP handler.
• The ea-ruby27-mod_passenger Apache module must be installed. When the ea-nginx-standalone module is installed, the system will automatically install this and other necessary Ruby modules if they are not already present.

  Note:

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

Compatibility

NGINX assumes the role of the primary web server. During installation, Apache will be reconfigured to use different ports than its default settings.

For additional details, please consult the NGINX Configuration Changes section below.

Note: Apache can still be utilized to serve dynamic content, but all requests must be proxied to the server.

Install or Uninstall NGINX

Install

Note: If the Experimental Repository is not already present on your server, install it using the following command:

yum install ea4-experimental

To install NGINX, execute the following command in the command line:

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

Uninstall

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

yum erase ea-nginx-standalone

The NGINX Installation Process

When you install the cPanel & WHM version of NGINX, the installation process modifies your server’s Apache installation to use alternative ports.

Note: This process will only adjust your Apache ports if your Apache configuration currently uses the default ports 80 and 443.

Upon NGINX installation, the ea-ruby27-mod_passenger Apache module is also installed. This module is mandatory.

The following features will function seamlessly with NGINX without requiring any further user action:

• 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 operate correctly if PHP-FPM is actively used.

NGINX Configuration Changes

Installing NGINX on your server initiates several system modifications.

Most notably, Apache is configured to no longer function as the primary web server. Consequently, the NGINX installation establishes proxies for Mailman and AutoSSL.

Configuration Files

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

Custom Configurations

Warning:

• Do not directly edit any files owned by NGINX. Modifying these files may lead to unexpected behavior.
• Creating custom configuration files can alter NGINX behavior in unintended ways. For example, if your custom block matches the PHP block, the server might serve the source code instead of processing PHP.

If you wish to customize server blocks for NGINX, create an include file ending in .conf within the appropriate directory. A server block is analogous to a virtual host in Apache.

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

For more information on server blocks, including practical examples, refer to NGINX’s Server Block Examples documentation.

Note: Do not use cpanel- as a prefix for any custom files you create.

Global Configuration

Any global .conf files you create should be placed in the /etc/nginx/conf.d/ directory.

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

Note: Ensure that you also reference your .conf file with an include directive in the file where you intend to use it.

User Configuration

Note: In the examples below, username represents the user’s account name, 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 owned by a specific user, create your .conf file in the following directory:

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

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

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

Apache Configuration

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

• Changes the Apache port to the first available port under 1024. This is typically port 81. Any applications that are not static must be proxied to Apache.
• Changes the Apache SSL port to the first available port under 1024. This is typically port 444.

  Note: Your Apache ports will only change if your configuration uses the default ports 80 and 443. Custom port numbers are ignored by the installation.

• Adds the following configuration 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

By default, NGINX does not serve files that begin with .ht. You may also need to restrict access to other files.

The simplest approach is to avoid including restricted-access files within the document root. However, if this is not feasible, you can explicitly restrict access to specific files.

For instance, if your website is served from a Git repository, you might want to prevent access to the site’s .git directory. To achieve this, create a .conf file in the appropriate location and add the following commands:

1
2
3
4
5
6

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

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

For additional details, consult the NGINX Location Priority documentation.

CloudFlare® Integration

The NGINX installation automatically detects if a domain utilizes CloudFlare and configures the system for proper operation.

The CloudFlare configuration is stored at the following location:

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

If your secure connections do not appear in the SSL log, you can adjust the SSL settings within CloudFlare.

Log Files

NGINX manages log rotation using the logrotate utility. This implies that WHM’s cPanel Log Rotation Configuration interface (WHM » Home » Service Configuration » cPanel Log Rotation Configuration) will not influence NGINX log rotation. This activity will still be recorded in your user statistics and bandwidth programs.

NGINX employs the default Apache log formats provided by cPanel & WHM. It will not recognize any custom Apache log formats. NGINX logs cannot be managed through interfaces specifically designed for Apache logs, such as WHM’s Log Rotation interface (WHM » Home » Service Configuration » Log Rotation). Apache will not log any requests that NGINX proxies to it.

NGINX logs traffic for the www subdomain to the same location as non-www subdomains, mirroring Apache’s behavior. For example, requests for www.example.com and example.com will both be logged to the /var/log/nginx/domains/example.com file.

NGINX uses the same server block for both SSL and non-SSL requests. However, it processes requests differently depending on whether piped logging is enabled.

Piped Logging

When piped logging is active, 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 records requests to the following location:

/var/log/nginx/access.log

Regular Logging

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

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

  Note: These files will also include an additional column at the beginning, formatted as domainname:port.

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

Redirects

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

• Redirects apply to the entire server block, not exclusively to the exact fully qualified domain name (FQDN). If a redirect is set for one domain, it will also affect any other FQDN within that block.
• Redirects apply to both www and non-www subdomains, irrespective of Apache’s behavior. This behavior can be altered using include files.
• Redirects do not automatically change HTTP requests to HTTPS. To enable this, use the Force HTTPS Redirect option in cPanel’s Domains interface (Home » cPanel » Domains » Domains).
• Redirects pointing to an index.html file will 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, that index file will be served instead.

• 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. Please use an alternative browser, or log in via the service’s port URL.

Using Include Files to Change Redirect Behavior

Include files can be used to compel NGINX to redirect www domains to non-www domains, or vice versa. These include files are not suitable for parked domains or for redirecting HTTP to HTTPS.

To implement this, we have provided the following include files. You can create a symbolic link that points to one of these files to modify 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 symbolic links, as this will result in an infinite loop.
• You must execute the /usr/local/cpanel/scripts/ea-nginx script command after creating your .conf file.

To establish redirect behavior for all domains belonging to a user, add the following symbolic link, where redirect-file is one of the files mentioned above and username represents the user:

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

To configure redirect behavior for only specific domains, add the following symbolic link, where redirect-file is 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 execute 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

Running 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 CentOS 7 restart commands for NGINX, you must employ the reload option. This option ensures a graceful restart:

systemctl reload nginx.service

For further information, please consult our How to Restart Services documentation.

Configuring a User

Note: Your NGINX configuration may take several minutes to update if you modify your PHP version or PHP-FPM configuration, enable or disable PHP-FPM, or add WordPress.

The system utilizes the /usr/local/cpanel/scripts/ea-nginx script to implement these changes. You are not required to manually run this script.

The system generates the .conf file in the following location, where username represents the user’s account name:

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

Configuring an Application

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

Limitations

If one of your domains conflicts with a proxy domain, the system will issue a warning indicating that conflicting duplicate entries will be ignored. This conflict may lead to unexpected behavior.

Warning:

• If you are using NGINX and ModSecurity® 2, your ModSecurity rules will only apply when NGINX proxies the request to Apache.
• Any restrictions configured in an .htaccess file will not be enforced. For example, if a directory is password-protected via .htaccess, the protection will not function.
• If you create an alias, ensure that your path’s location ends with a trailing slash (/). If your path does not end with a /, it is vulnerable to a path traversal exploit.
• For more detailed information, consult the NGINX Security Advisories documentation.

Troubleshooting

Could not build the server_names_hash Error

You may encounter an error message similar to the following:

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 this error occurs, increase the value of the following directives in both the /etc/nginx/conf.d/ea-nginx.conf and /etc/nginx/ea-nginx/settings.json files:

• server_names_hash_max_size
• server_names_hash_bucket_size

For more information, refer to the NGINX Server Names documentation.

NGINX Will Not Restart

If you initiated NGINX using the nginx command, then the /usr/local/cpanel/scripts/restartsrv_nginx and systemctl restart nginx.service commands will not function correctly. To resolve this issue, follow these steps:

1. Stop the service with the /usr/sbin/nginx -s stop command.
2. Restart NGINX using one of the following commands:
   • /usr/local/cpanel/scripts/restartsrv_nginx start
   • systemctl start nginx.service
   • /etc/init.d/nginx start

WordPress Multisite Incompatibility

WordPress Multisite installations are currently incompatible with cPanel & WHM servers configured with NGINX.

Can’t Use Pretty Permalinks with WordPress

WordPress installations will not inherently support Pretty Permalinks when NGINX is used. To address this, add the following information to your NGINX configuration file, where php## denotes the version of PHP running on your server and 1ed179754201ac2644e8c70140bacb23c7786484 represents the PHP-FPM socket through which WordPress operates:

Note:

• To obtain the correct PHP-FPM socket, execute the following command, where username represents the user’s account name:

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

• Ensure you follow the instructions in the Configuring a User section of this document to prevent NGINX from overwriting 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;
    }
}