Last modified: August 21, 2024
Overview
- 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 ourea-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.
- Previous versions of the
ea-nginx
package installed Apache’s Passenger package by default. If you want to use Passenger, you must install theea-apache24-mod-passenger
package. If Passenger already exists on your server, it will remain on your server. - For more information, read our Using Passenger Applications documentation.
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.
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:
- 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.
- NGINX redirects any non-SSL IPv6 requests to use SSL. This ensures that any IPv6-only service subdomains will work correctly. If your client will not accept the hostname’s security certificate, we recommend that you use the subdomain’s fully-qualified domain name instead.
- 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 a custom NGINX configuration that uses the NGINX
alias
directive, 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:
Operating System | Command |
---|---|
CentOS 7 | yum install ea-nginx |
AlmaLinux OS and Rocky Linux™ | dnf install ea-nginx |
Ubuntu® | apt install --purge 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:
Operating System | Command |
---|---|
CentOS 7 | yum uninstall ea-nginx |
AlmaLinux OS and Rocky Linux™ | dnf uninstall ea-nginx |
Ubuntu® | apt purge 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.
The process will only change your Apache ports if your Apache configuration uses the default ports of 80
and 443
.
NGINX also installs the mod_remoteip
Apache module if it does not already exist. This module ensures that the system properly sets the REMOTE_ADDR
variable to the correct IP address when requests are proxied to Apache. For more information, read the Apache mod_remoteip section below.
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.
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/proxy/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.
Your application’s requests for dynamic content should include cache control headers. If they do not, 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.
Custom cache keys
You can set your NGINX cache to generate separate caches for different conditions. For example, you may want to cache mobile and non-mobile requests separately.
To configure your cache to use separate caches in varying conditions, set the $CACHE_KEY_PREFIX
in the /etc/nginx/conf.d/includes-optional/set-CACHE_KEY_PREFIX.conf
file. We include this file by default, with the option to cache mobile requests separately commented out.
For more information about proxies in NGINX, read the NGINX Proxy documentation.
Use htaccess to manage caching
You can also use your .htaccess
files to manage caching in NGINX. If you use this method, your .htaccess
file will set the header in your requests to handle caching for any requests your application does not set.
Your applications should set appropriate headers to ensure that sensitive data is not cached. If you cannot update your application to send appropriate headers, then you can use your .htaccess
file. The entry in your .htaccess
file might resemble the following example:
|
|
If your application does not use proper headers for sensitive data, it is a security risk.
Add the following to your .htaccess
file to enable caching for common static files:
|
|
Your application’s requests for dynamic content should include cache control headers. If they do not, the server may return cached responses that do not apply to the user.
Configuration files
The system creates the /etc/nginx/conf.d/ea-nginx.conf
configuration file. NGINX uses .conf
configuration files for direct configuration.
It also creates the following files when you install the ea-nginx
package:
/etc/nginx/ea-nginx/settings.json
/etc/nginx/ea-nginx/cache.json
The ea-nginx
script uses files that end in .json
to specify the values when it generates configuration files.
Configuration settings
You can set the following directives for NGINX in WHM’s Global Configuration interface (WHM » Home » Service Configuration » Apache Configuration » Global Configuration). The following values in the Global Configuration interface correspond to the following directives:
- Keep-Alive — This directive corresponds to the
keepalive
directive. If you set this value toOn
, NGINX uses a value of32
. If you want to use a different value, set thekeepalive
value to a valid number in the/etc/nginx/ea-nginx/settings.json
file. - Keep-Alive Timeout — This directive corresponds to the
keepalive_timeout
directive. NGINX only uses the value set in WHM’s Global Configuration interface. - Max Keep-Alive Requests — This directive corresponds to the
keepalive_requests
directive. NGINX only uses the value set in WHM’s Global Configuration interface.Note:If you set this value toUnlimited
in the Global Configuration interface, then NGINX uses a value of1000
.
Custom configurations
- 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.
To customize your NGINX configuration before you install the ea-nginx
package, you can create the following files:
/var/nginx/ea-nginx/settings.json
/var/nginx/ea-nginx/cache.json
If these files exist when you install NGINX or rebuild your NGINX configuration, the system will copy them to the /etc/nginx/ea-nginx/settings.json
and /etc/nginx/ea-nginx/cache.json
files respectively, then delete the original files. For more information, read the Configuration settings section.
We also support the following directives in the /var/nginx/ea-nginx/settings.json
file:
keepalive_time
Note:No Apache equivalent exists for thekeepalive_time
value.worker_shutdown_timeout
worker_processes
If you create these files, they must contain valid JSON. Invalid JSON files may cause your installation to fail.
Server blocks
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/
directory.
For more information about server blocks, including examples, read NGINX’s Server Block Examples documentation.
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.
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
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 port81
. - Changes the Apache SSL port to the first available port under
1024
. This will usually be port444
.Note:Your Apache ports will only change if your configuration uses the default ports80
and443
. 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; }
Apache mod_remoteip
The NGINX installation installs the Apache mod_remoteip
module if it does not already exist.
When NGINX installs this package, it edits the proxy configuration files. This ensures that the system properly sets the REMOTE_ADDR
variable to the correct IP address when requests are proxied to Apache.
This allows NGINX to securely proxy to Apache and prevents spoofed IP addresses via mod_remoteip
.
-
If you customized your
/var/cpanel/templates/apache2_4/ea4_main.local
file, then you must update the file based on the contents of the/var/cpanel/templates/apache2_4/ea4_main.default
file. -
If you already installed the
mod_remoteip
module, we recommend that you remove the following entries from your include files:RemoteIPHeader
RemoteIPInternalProxy
This ensures that your configuration uses the provided secure settings.
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:
|
|
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 configures the system to work properly with CloudFlare.
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.
The /usr/local/cpanel/scripts/runweblogs
script does not process logs for NGINX.
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, indomainname: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.
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
Use cPanel’s Application Manager interface (Home » cPanel » Software » Application Manager) to configure applications.
NGINX-specific packages
We provide some additional packages that you can use with NGINX. These packages provide functionality that may otherwise be missing in the installation.
Compression
We provide the gzip and Brotli packages to enable compression on NGINX. If you install one of these packages, it will enable that compression globally.
If you use compression with SSL/TLS requests, your compressed responses may be vulnerable to BREACH attacks. To lower the risk of this type of attack, you can perform one of the following actions:
- Do not send sensitive data in your HTTP responses.
- Limit your responses to only use secure samesite cookies.
Brotli
To use Brotli, install the ea-nginx-brotli
package in the Additional Packages section of WHM’s EasyApache 4 interface (WHM » Home » Software » EasyApache 4)..
You can use the /etc/nginx/conf.d/brotli.conf
configuration file to configure your Brotli installation. For more information about configuring Brotli, read the NGINX Brotli module documentation.
gzip
To use gzip, install the ea-nginx-gzip
package in the Additional Packages section of WHM’s EasyApache 4 interface (WHM » Home » Software » EasyApache 4).
You can use the /etc/nginx/conf.d/gzip.conf
configuration file to configure your gzip installation. For more information about configuring gzip, read the NGINX gzip module documentation.
HTTP2
To use HTTP/2 with NGINX, you must install the ea-nginx-http2
package. You can install this package in the Additional Packages section of WHM’s EasyApache 4 interface (WHM » Home » Software » EasyApache 4).
When you install the ea-nginx-http2
package, the system creates the /etc/nginx/conf.d/http2.conf
file. This is a comment-only file that you can use to set your system’s HTTP/2 configuration. NGINX only supports HTTP/2 via SSL. NGINX terminates the protocol when it sends a proxy request to Apache that uses HTTP/2. NGINX uses HTTP 1.1 to communicate with Apache.
We don’t require the Apache mod_http2
module if you wish to use HTTP/2 on a system that runs NGINX.
NGINX JavaScript Module (NJS)
The NGINX JavaScript module (NJS) allows you to use NGINX’s JavaScript-based scripting language with your NGINX server. To use NJS, install the ea-nginx-njs
package in the Additional Packages section of WHM’s EasyApache 4 interface (WHM » Home » Software » EasyApache 4).
You can use the /etc/nginx/conf.d/njs.conf
configuration file to configure your NJS installation.
For more information, read the NGINX NJS documentation.
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, 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 exist, 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 proxy_headers hash
You may receive an error that resembles the following message:
|
|
If you receive this error message, one of your .conf
files contains a proxy_set_header
directive that sets a very long header name. To correct this error, add the following directive to the .conf
file that contains the long proxy_set_header
directive, where number
represents a header length:
proxy_headers_hash_bucket_size number;
You must add this directive immediately before the long proxy_set_header
directive.
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:
-
Stop the service with the
/usr/sbin/nginx -s stop
command. -
Restart NGINX with one of the following commands:
/usr/local/cpanel/scripts/restartsrv_nginx start
systemctl start nginx.service
/etc/init.d/nginx start