Search Our Database
WHM/cPanel | Configuring Apache ProxyPass
Introduction
Apache ProxyPass lets a cPanel & WHM server forward requests for a specific website path to an application hosted on another server. This guide shows how to configure a domain-specific reverse proxy using an Apache include file in EasyApache 4, while leaving the rest of the website hosted on cPanel.
Example traffic flow:
Visitor (HTTPS) → cPanel Apache → backend application (HTTP).
Visitor (HTTPS) → cPanel Apache → backend application (HTTPS).
Prerequisites
- Root or authorized administrative SSH access to a cPanel & WHM server using EasyApache 4 and Apache 2.4.
- A working domain with a valid HTTPS certificate, website document root.
- An HTTP backend that is reachable from the cPanel server.
- Apache proxy modules enabled.
- An approved change window.
- Understand the underlaying concept from official forums : https://support.cpanel.net/hc/en-us/articles/1500011220222-How-do-you-create-an-Apache-Reverse-Proxy-with-mod-proxy
Important Note
- This procedure changes Apache server configuration and requires administrative access. Rebuilding and restarting Apache may briefly affect hosted websites.
- Replace all sample values. example.com, exampleuser, and IP addresses.
- If you modify an existing website .htaccess file, back it up and preserve application rewrite rules. Avoid duplicate or conflicting HTTPS redirects.
- Do not edit the generated Apache httpd.conf directly.
Step-by-step guide
Step 1: Identify the cPanel account and Apache virtual host
Check the domain mapping and active virtual hosts before choosing the include path:
apachectl -S
Identify the actual cPanel username and virtual host name. For an addon domain or alias, the virtual host name may differ from the public domain. Use the virtual host name for the include directory.
Step 2: Confirm the required Apache modules
Both proxy_module and proxy_http_module should appear for the reverse proxy. The rewrite_module is additionally needed only if you use the optional .htaccess redirect shown later. Review the EasyApache 4 configuration if a required module is absent.
Step 3: Verify the backend route from cPanel
For this example, visitors will use https://www.example.com/portal/ and Apache will forward that path to an HTTP backend at 123.123.123.123:
Use the actual backend address and path. A successful application response (commonly HTTP 200) indicates that the backend is reachable.
HTTP 502, timeouts, or connection refusals must be resolved before enabling the proxy. The correct backend path should be confirmed with the application owner.
Step 4: Create the domain-specific SSL include file
cPanel’s include directories are selected according to the incoming request protocol:
| Incoming protocol | Apache include path |
|---|---|
| HTTPS (443) | /etc/apache2/conf.d/userdata/ssl/2_4/USER/VHOST/NAME.conf |
| HTTP (80) | /etc/apache2/conf.d/userdata/std/2_4/USER/VHOST/NAME.conf |
For an HTTPS public URL, create the SSL include directory and open the new file.
The example assumes the username is exampleuser and the Apache virtual host is example.com:
vi /etc/apache2/conf.d/userdata/ssl/2_4/exampleuser/example.com/portal_proxy.conf
If the file already exists, back it up before editing:
Step 5: Add the ProxyPass rules
Part 1 (if backend HTTP)
For a backend that serves the same /portal/ path, in /etc/apache2/conf.d/userdata/ssl/2_4/exampleuser/example.com/portal_proxy.conf
add:
ProxyPass “/portal/” “http://123.123.123.123/portal/”
ProxyPassReverse “/portal/” “http://123.123.123.123/portal/”
- ProxyPass : forwards the matching URL path to the backend.
- ProxyPassReverse : adjusts supported redirect response headers.
- ProxyPreserveHost On : forwards the visitor’s Host header; use it when required by the backend application’s virtual-host configuration.
If the backend instead serves the application at its root path, the destination mapping can be changed to:
ProxyPass “/portal/” “http://123.123.123.123/”
ProxyPassReverse “/portal/” “http://123.123.123.123/”
Choose one destination mapping based on the actual backend route. Preserve the trailing slash on both sides of each mapping.
The ssl/2_4 directory means that visitors connect over HTTPS; it does not require the backend to use HTTPS.
SSLProxyEngine On is relevant when Apache must connect to an HTTPS backend, not for this HTTP example.
Part 2 (if backend HTTPS)
If the backend server uses HTTPS instead of HTTP, enable SSLProxyEngine in the Apache configuration.
Configuration File
Example configuration for HTTPS → HTTPS:
SSLProxyEngine On
ProxyPreserveHost On
ProxyPass “/portal/” “https://123.123.123.123/portal/”
ProxyPassReverse “/portal/” “https://123.123.123.123/portal/”
- SSLProxyEngine On: Enables Apache to establish HTTPS connections to the backend server.
- ProxyPreserveHost On: Preserves the original client Host header when forwarding requests.
- ProxyPass: Forwards requests from the specified application path to the HTTPS backend.
- ProxyPassReverse: Rewrites applicable redirect headers returned by the backend.
Step 6: Check the existing HTTP-to-HTTPS redirect and .htaccess file
For this example, the reverse proxy is configured only for incoming HTTPS requests.
HTTP requests should redirect to HTTPS instead of requiring a second ProxyPass include under std/2_4. First, check whether the redirect is already in place:
If the response is a redirect to the intended HTTPS URL, do not add another redirect rule. It may already be configured through cPanel’s Force HTTPS Redirect feature or the existing website configuration.
If the redirect is missing, locate the website’s actual document root from Step 1. Check whether it already contains a .htaccess file. Replace the example document-root path below with the verified path:
- If .htaccess exists: Back it up outside the public document root, inspect its current redirect and rewrite rules, and add the HTTPS redirect only if necessary. Place the new rule before the WordPress rewrite block or other catch-all rewrites. Never overwrite the existing file or duplicate a working redirect.
- If .htaccess does not exist: With the site owner’s approval, create it inside the verified document root, preserving the correct file ownership and permissions for that account.
When a manual HTTPS redirect is required, add the following generic example to the existing or newly created .htaccess file:
RewriteEngine On
RewriteCond %{HTTPS} off
RewriteRule ^ https://www.example.com%{REQUEST_URI} [R=301,L] </IfModule>
Use the site’s actual canonical HTTPS hostname in place of www.example.com. This example redirects HTTP to HTTPS while preserving the requested URL path. Test carefully if the site is behind an additional TLS-terminating proxy, because HTTPS detection may differ. A conflicting redirect can cause a loop.
Re-run the HTTP check above and confirm a 301 response with the correct Location header. Editing .htaccess takes effect on subsequent requests and does not itself require an Apache restart. If the redirect behaves unexpectedly, restore the previous .htaccess content.
Step 7: Rebuild the Apache configuration and test syntax
apachectl -t
Proceed only when Apache reports Syntax OK.
Step 8: Restart Apache
This activates the rebuilt Apache configuration. Perform the service restart during an approved window.
Validation
Step 9: Verify the include and public URL
Confirm Apache has loaded the include:
Test the public HTTPS URL directly against the intended cPanel Apache IP, bypassing normal DNS selection. Replace the sample origin IP and domain:
An expected application status, often HTTP 200, confirms the route is responding. Avoid using -k for final verification because it bypasses TLS certificate validation.
If HTTP requests are configured to redirect to HTTPS, check that separately:
Expected: an HTTP redirect, typically 301, with a Location header pointing to the HTTPS URL. If the HTTP-to-HTTPS redirect works, a separate non-SSL ProxyPass include is unnecessary. If it does not, follow Step 6 to inspect the existing redirect configuration and use the .htaccess method only when appropriate.
Finally, open the page in a browser and inspect its network requests. Confirm that JavaScript, CSS, images, form submissions, navigation, and other website paths all function correctly.
Important URL-path considerations
- HTML is not enough: HTTP 200 for the landing page does not guarantee that static assets or API endpoints are accessible.
- Root-relative resources: An application using URLs such as /assets/site.css may request resources outside the proxied /portal/ prefix. The application should support its intended public base path, or a separate, narrowly scoped routing design is required.
- Backend health: HTTP 502 from the backend itself generally indicates an upstream service problem; test the backend directly before changing Apache.
- Other hosted content: Do not add a catch-all ProxyPass “/” rule when the existing website must remain on cPanel.
Rollback
If the change causes problems, restore the previous include content from the backup (or disable the newly added include by comment it with #), rebuild the Apache configuration, verify syntax, and restart Apache. Recheck the original website and affected route after rollback.
Summary
Scenario 1: htaccess already redirects HTTP to HTTPS
Only one ProxyPass configuration file is required, under the SSL VirtualHost:
/etc/apache2/conf.d/userdata/ssl/2_4/USER/VHOST/NAME.conf
HTTP requests will redirect to HTTPS based on .htaccess, and Apache will forward HTTPS requests to the backend.
Scenario 2: No HTTP-to-HTTPS redirect is configured
If both HTTP and HTTPS requests must be proxied directly, create two ProxyPass configuration files:
- HTTP: /etc/apache2/conf.d/userdata/std/2_4/USER/VHOST/NAME.conf
- HTTPS: /etc/apache2/conf.d/userdata/ssl/2_4/USER/VHOST/NAME.conf
Recommendation: For HTTPS websites, redirect HTTP traffic to HTTPS and maintain ProxyPass in the SSL VirtualHost only. This avoids unnecessary duplicate proxy configurations.
References
- cPanel & WHM: Modify Apache Virtual Hosts with Include Files
- cPanel & WHM: Advanced Apache Configuration
- Apache HTTP Server: mod_proxy Directives
- Apache HTTP Server: Reverse Proxy Guide
Through technology, we learn. Through sharing, we connect.
Explore more guides at https://kb.ipserverone.com/
For technical support / service enquiries, please reach out to support@ipserverone.com for assistance.