Cachewall is a feature-rich software package providing simple management of Varnish Cache, the open source high-performance HTTP accelerator developed by Poul-Henning Kamp, Varnish Software, and numerous open source contributors to their project.
The Cachewall control panel software has been created for use with cPanel on shared web hosting servers, but we hope that it is useful to others in any similar applications. Work is underway to support non-cPanel systems and alternative backends, such as LiteSpeed and Nginx.
Cachewall is production-ready for all cPanel versions and provides an immediate, significant improvement in website performance. While it's heavily dependent on traffic characteristics, we've seen numerous cases where CPU utilization by PHP/CGI scripts is reduced by over 50% - without negatively impacting website visitors!
The Cachewall software has been under active development and used in production shared web hosting since 2014.
We are currently providing limited support while we work on our next update. Thank you for your patience.
Latest Version: Edge 0.38.4-2, February 19th, 2018 - Changelog is available here.
January 20th, 2018 Cachewall 0.38 is now available on our release repository. Please review the details below, this update contains significant changes to our package names, our dependencies, our YUM repository configuration files. - We renamed our RPM packages to `cachewall` and `cachewall-vmods`. These were formerly named `xvarnish` and `xvarnish-vmods`. - We introduced the `cachewall-release` package as a dependency on the `cachewall package`. This new package distributes the Cachewall and Varnish Cache 4.1 YUM repository configurations (cachewall.repo, varnish-41.repo) along with our GPG signature public key. - We removed our dependency on packages `xvarnish-repository` and `varnish-release`. These will be obsoleted in Cachewall 0.40. It should not cause any problems to leave either installed alongside Cachewall 0.38. - We've updated our GPG key for RPM package signing to key ID E04F4A3A (Cachewall Software). - We renamed the Cachewall YUM repositories to be more consistent: cachewall-stable, cachewall-release, cachewall-edge, cachewall-development From this point forward, users may simply install the `cachewall-release` and `cachewall` packages to get started. Upgrading from an earlier version should be seamless via `yum update xvarnish` (i.e., upgrading from the `xvarnish` package names). Please note that upgrading from an earlier version (0.36 or lower) will momentarily disable Cachewall if it is enabled prior to the update. Please get in touch at email@example.com if you discover any problems. While we've tested the changes extensively, there are a lot of moving parts with the package changes here. January 4th, 2018 Happy New Year! We have a number of updates coming soon. April 18th, 2017 We've started gathering help documentation for our knowledge base at https://help.cachewall.com. Feel free to send any suggestions if there's a feature you'd like to see explained in-depth.
Cachewall is compatible with cPanel under both CentOS 6 and CentOS 7 (including CloudLinux 6 and CloudLinux 7). The software may be installed in both dedicated and virtual server environments. Cachewall works with all cPanel versions, EasyApache 3, EasyApache 4 (see Note for EA4), and LiteSpeed WebServer.
To install Cachewall, run:
rpm -ivh https://repo.cachewall.com/cachewall-release.rpm
yum install cachewall
Note for EA4: If you're using cPanel EasyApache 4 you should install the ea-apache24-devel cPanel package. This provides apxs which is necessary to configure xVarnish mod_xvarnish for visitor IP address correction. See Real Client IPs with Apache for more information.
Please get in touch if you experience any problems. We will work with you to troubleshoot and promptly issue a bugfix if necessary.
To upgrade Cachewall, run:
yum update cachewall
The installation provides a completely hand-free setup of your server for Cachewall and Varnish Cache.
You should now register on cachewall.com by entering your email address if you have not already done so. You will be immediately sent new account access information for the Cachewall license manager and after signing in, you can create a license key for any number of servers. There is no cost currently for using Cachewall on any number of servers, and when that changes there we will provide notification at least 2 months in advance. (Written January, 2018)
A WebHost Manager plugin is installed for management, and you may also use the xvctl utility for equivalent management functionality via the command line (see
Once you have your license key, run:
/usr/local/xvarnish/bin/activate --key <license-key>
Cachewall is not enabled automatically by default. Once you're ready you can simply access the Cachewall plugin under WebHost Manager to make the web server switch. You can run this right from the command line too:
xvctl enable cachewall
xvctl enable https
During the enable process, your traditional HTTP service (Apache, LiteSpeed, etc) is configured to listen on HTTP port 0.0.0.0:82 to serve as the backend for Varnish Cache, and Varnish Cache is configured to listen on HTTP port 0.0.0.0:80. Varnish Cache receives requests and if necessary, forwards them to the HTTP backend to retrieve the response. When Cachewall HTTPS is enabled, your traditional HTTPS service is configured to listen on port 0.0.0.0:445, and Hitch is configured to replace it on HTTPS port 0.0.0.0:443. Hitch terminates TLS and proxies plaintext requests to Varnish Cache via PROXY port 127.0.0.1:6086, where the request is then sent to the HTTPS backend if necessary. These changes are reverted when Cachewall is disabled, and the involved port numbers are configurable if necessary.
Want to live on the edge? Install the latest testing release with:
yum install cachewall --enablerepo=cachewall-edge
Cachewall's xvctl utility provides the -v option to enable debug output and logging. If you're facing troubles, it's usually helpful to add this argument onto your command. You can actually specify -v multiple times to increase verbosity. For example:
xvctl -vvv enable https
It's also possible to enable debug logging in the Cachewall configuration file. Edit /usr/local/xvarnish/settings and set log_level = DEBUG. You'll see debug log messages written into var/log/xvarnish/xvarnish.log when xvctl runs. The xvhealth and xvstats service must be restarted before they'll pick up changes to log_level.
You may set LOG_ECHO=1 in your environment to enable debug logging for xvctl (
export LOG_ECHO=1). Use this variable to enable debug logging for problems during installation and upgrades:
export LOG_ECHO=3 yum update cachewall
Cachewall may be disabled at any time via the WebHost Manager plugin, and the disable process immediately reverts all cPanel and web service configurations to their original. If you experience a significant problem you should disable Cachewall and get in touch with our support. To immediately disable Cachewall and Varnish Cache, run:
xvctl disable cachewall
Use the revert-apache.sh shell script if xvctl is not functional:
Run the command below to fully uninstall Cachewall. Please note that we recommend disabling Cachewall but leaving it installed in the event you're experiencing a significant problem. Cachewall performs the same configuration revert during disable as it would for a full uninstall; the software shouldn't impact your service while its disabled. This helps us greatly while investigating any support help requests.
To uninstall, run:
yum remove cachewall cachewall-vmods cachewall-release varnish
Cachewall leaves some configuration files in /usr/local/xvarnish and log files in /var/log/xvarnish. If you wish to remove everything, run:
rm -rI /usr/local/xvarnish /var/log/xvarnish
Please see: Cachewall Technical Support Guide
CHANGELOG cachewall-release.rpm NEWS getting-started-readme.txt revert-apache.sh setup-debug-varnishlog.sh authsecret.sh cacheperf.sh
Edge 0.38.4, 2018-02-19 - [Case 515] Fixed AutoSSL Domain Control Validation (DCV) requests failing for cPanel proxy subdomain certificates. - [Case 516] Fixed Statistics (xvstats) TypeError "
object is not callable" when the initial VSM connection fails. - [Case 517] Improved the clarity of error messages for license activation verification failures. Stable 0.38.3, 2018-02-08 - [Case 509] Fixed failure reading cache memory option values with SI suffix (i.e., 256M). - [Case 510] Work around memory setting read potentially missing value during enable process ("bin/xvbash: line 110: $2: unbound variable"). Release 0.38.2, 2018-01-31 - [Case 507] Dashboard Real-time Traffic chart improvements; added button to pause updates and improved styling. Edge 0.38.1, 2018-01-25 - [Case 469] Fixed potential wrong pidfile directory ownership following a package update for Hitch. - [Case 471] Fixed bogus activation and pidfile directory errors for new installations. - [Case 479] Fixed Varnish Cache configuration reload timestamp recording under CentOS 7 (VCL age tracking). - [Case 474] Fixed Real-time Web Traffic chart breaking when dashboard loses focus for some length of time. - [Case 485] Fixed Real-time Web Traffic chart synthetic request counts including ratelimit and firewall request counts. - [Case 489] Fixed Real-time Web Traffic chart losing past data points after statistics data stream is interrupted. - [Case 490] Fixed Real-time Web Traffic chart updates failing in some cases after Varnish Cache is restarted. - [Case 491] Add 'Ratelimit Exceeded' to Real-time Web Traffic chart. - [Case 429] Add 'Blocked by Firewall' to Real-time Web Traffic chart. - [Case 492] Add 'Ratelimit Exceeded' runtime statistic to Client Responses chart. - [Case 493] Add 'Blocked by Firewall' runtime statistic to Client Responses chart. - [Case 478] Fixed potential orphaning of Cachewall stunnel processes. - [Case 494] Fixed service handling potentially stopping stunnel processes that are unrelated to Cachewall. - [Case 495] Fixed Cachewall version lookup (via xvctl status) failing to find package name. - [Case 486] Record varnishstat details in system report archive generated by report.sh. - [Case 496] Fixed configuration update hook for memory option failing with rstrip AttributeError. - [Case 484] Fixed unnecessary mod_xvarnish rebuild after every upgrade or enable. - [Case 497] Fixed unnecessary xvhealth service stop in post-enable.sh. - [Case 498] Speed up enable and disable processes by running time consuming operations in parallel. - [Case 499] Add link back to WebHost Manager interface in plug-in. - [Case 501] Bring license activation utility up to date for backend licensing system. - [Case 503] Fixed automatic configuration refresh for HTTPS/SSL certificate changes in cPanel 66 and earlier. Release 0.38, 2018-01-20 From this point forward, users may simply install the `cachewall-release` and `cachewall` packages to get started. Upgrading from an earlier version should be seamless via `yum update xvarnish` (i.e., upgrading from the `xvarnish` package names). Please note that upgrading from an earlier version (0.36 or lower) will momentarily disable Cachewall if it is enabled prior to the update. Edge 0.38, 2018-01-16 This release focuses on improvements to our package repository. We've renamed our packages from the legacy xvarnish name to cachewall and also simplified our installation steps. Upgrading to 0.38 should be seamless; running `yum update xvarnish` is expected to handle the changes without issue. - We renamed our RPM packages to `cachewall` and `cachewall-vmods`. These were formerly named `xvarnish` and `xvarnish-vmods`. - We introduced the `cachewall-release` package as a dependency on the `cachewall package`. This new package distributes the Cachewall and Varnish Cache 4.1 YUM repository configurations (cachewall.repo, varnish-41.repo) along with our GPG public key used for validating package signatures. - We removed our dependency on packages `xvarnish-repository` and `varnish-release`. These will be obsoleted in Cachewall 0.40. It should not cause any problems to leave either installed alongside Cachewall 0.38. - We've updated our GPG key for RPM package signing to key ID E04F4A3A (Cachewall Software, firstname.lastname@example.org). - We renamed the Cachewall YUM repositories to be more consistent: cachewall-stable, cachewall-release, cachewall-edge, cachewall-development Release 0.36.3, 2017-01-08 - [Case 477] SSL certificates not updating automatically. Release 0.36.2, 2018-01-06 - [Case 476] Additional cPanel 68 SSL change fix. Edge 0.36.2, 2018-01-04 - [Case 467] Fixes for cPanel 68 SSL changes. Please test! Edge 0.36.1 - [Case 445] Add stunnel as a package dependency. - [Case 448] Fixed HTTP request matching for rule request patterns having the https:// scheme specified. - [Case 455] Fixed 'Enable Cachewall' prompt standby indicator and navigation/dismissal disallow after submitting. - [Case 456] Fixed UI not locking while Cachewall software is updating. - [Case 457] Fixed 'Save Configuration' prompt submitting after pressing cancel button. - [Case 458] Automatically update WebHost Manager plugin's AppConfig configuration. - [Case 460] Add events to status history for Cachewall Enable and Disable procedures. - [Case 461] Lock the UI while Cachewall is enabling and disabling. - [Case 462] Fixed UI inconsistency after a failed Cachewall enable. - [Case 463] Prevent Dashboard data polling from disrupting new WebHost Manager sessions. - [Case 465] Gracefully handle failure loading or polling Dashboard data. - [Case 466] Allow disabling Cachewall without --force when the configuration has it disabled. - Updated hello message. - Removed legacy xVarnish WebHost Manager link. - Merged expanded-realtime; improved web traffic and statistics charts. - Fixed potential ownership problem on /var/run/xvarnish. Release 0.36, 2017-06-12 - [Case 451] Carry over customized TTL configuration option values to their new option names. Edge 0.36, 2017-05-26 - [Case 449] Resolved WAF Traffic Analytics start failure if .xvbeat_registry is corrupted. ("Could not start registrar: Error decoding states: EOF") - [Case 450] Updated hitch.service systemd unit from Type=forking to Type=simple, to capture standard output and error in journald. (Should help troubleshoot cause of sporadic config reloads resulting in worker SIGABRT crashes.) - [Case 463] Fixed Dashboard chart script error under Internet Explorer. Edge 0.36, 2017-05-02 - Update to Varnish Cache 4.1.6. - Improved handling of request and response Cache-Control. Cache objects are now updated when the Cache-Control no-cache directive is present. - Automatically correct Hitch configuration CA chain certificate order if a bundle is found misordered. It appears cPanel Inc / COMODO AutoSSL CA bundles have this problem in particular. - Added bin/report.sh to simplify troubleshooting. Users can run this to gather Cachewall information and log files into a single tarball to provide for support. See: http://help.cachewall.com/article/50-cachewall-technical-support-guide - Added default PASS exclusion rule for request URL pattern: /.well-known/* - Renamed option listen_address to frontend_http_address. (Varnish Cache listen interface address for incoming HTTP requests) - Renamed option frontend_port to frontend_http_port. (Varnish Cache listen port number for incoming HTTP requests) - Renamed option hitch_be_address to frontend_proxy_address. (Varnish Cache PROXY address for the Hitch backend) - Renamed option hitch_be_port to frontend_proxy_port. (Varnish Cache PROXY port number for the Hitch backend) - Renamed option hitch_fe_address to frontend_https_address. (Hitch listen interface address for incoming HTTPS requests) - Renamed option frontend_port_https to frontend_https_port. (Hitch listen port number for incoming HTTPS requests) - Merged option hitch_fe_port into frontend_https_port. - Removed legacy unused options hitch_enable_ssl, hitch_enable_tls, sslproxy_be_port and sslproxy_fe_port. - Renamed option dynamic to dynamic_ttl. (Cached object time-to-live for dynamic responses) - Renamed option static to static_ttl. (Cached object time-to-live for static responses) - Split option object_grace_period into static_grace and dynamic_grace, allowing independent control over grace periods. - Fixed the frontend Hitch configuration not properly respecting the value of frontend_https_address. - Added remaining network-related settings options to the WebHost Manager Configuration page and grouped network options separately. - Returned the ability to automatically compress suitable response types. (See options gzip_responses and gzip_types) - Added option gzip_responses. (Toggles automatic response compression) - Added option gzip_types. (Plaintext responses with a Content-Type header matching this expression are compressed) - Changed memory option type from string to integer. (Earlier versions allowed an 'M' suffix on the value) - Fixed some advanced options displaying under Configuration when they shouldn't be. - Fixed WebHost Manager plug-in opening in a new window in cPanel 64. Release 0.35.6, 2017-04-07 - Also respect no-store and private response Cache-Control header value for option respect_response_cache_control. - Fixed implementation of settings option respect_request_cache_control. Release 0.34.4, 2017-04-06 - Fixed cPanel proxy subdomains redirecting to hostname + /cgi-sys/defaultwebpage.cgi with 'Require SSL' and 'Non-SSL redirect destination: Hostname' configured. - Fixed UnboundLocalError while generating HTTPS configuration if system hostname certificate is not installed. - Fixed ordering of certificate private key in Hitch configuration PEM files. - Fixed problem with static file objects having dynamic TTL applied. - Fixed inaccurate service status details (dropdown) shown initially on Licensing page. Release 0.34.3, 2017-03-30 - Fixed PHP templating error on the xVarnish rename intermediate page. Release 0.34.2, 2017-03-29 - Fixed PHP templating error shown in the WebHost Manager plug-in (license.php) for new\unlicensed systems. Release 0.34.1, 2017-03-29 - Added TLSv1.0 to the default TLS protocols in Cachewall option hitch_tls_protos (Hitch option tls-protos). - Tweaked styling Dashboard real-time and donut chart styling. - Fixed package version not showing in WebHost Manager plug-in page footers. - Fixed Dashboard requests chart y-axis scale when a gap is found in the timeseries. - Fixed Dashboard requests chart not remembering the last selected time period. - Fixed cPanel proxy subdomain cPPHP wrapper when executed outside of cpsrv. ("Cannot execute $path or path resolves back to $0.") - Fixed cPanel proxy subdomain redirect loop when 'Require SSL' is enabled in cPanel. - Fixed HTTPS certificate validation of Punycode representations for Unicode internationalized domain names (IDNs). - Fixed 301 and 302 status backend response caching (redirects); these always generated a hit-for-pass in earlier versions. - Reduced response hit-for-pass object TTL from 120s to 60s. - Improved HTTPS configuration handling; Notably, options defined in conf.d/default/hitch.conf are no longer overwritten. - Improved Hitch service (EL6): Test start failures without -t or --daemon, ensuring stderr is available for review. - Improved HTTPS port status check following a Cachewall update, enable, or disable. If backend is discovered listening on the Cachewall HTTPS port 445 and Cachewall HTTPS is disabled, cPanel option apache_ssl_port is set to HTTPS port 443 (0.0.0.0:443) and httpd.conf rebuilt. Release 0.34, 2017-03-20 - WAF Security Challenge redesign - Invisible reCAPTCHA! - Updated default response template designs (error pages, ratelimit reached, WAF, etc). - Resolved "Failed parsing last reload timestamp" Healthcheck errors. - Removed unused sslproxy_online Healthcheck module that was missed in the previous update. - Improvements to WAF traffic analysis. Release 0.33, 2017-03-16 - Resolved fatal error shown while loading Error Pages in WebHost Manager and renamed this to Templates. - Fixed cPanel Webmail (Horde, SquirrelMail) generating invalid URLs and/or using wrong HTTP/HTTPS port numbers. - Removed legacy xvssl service. Edge 0.32.1, 2017-03-13 - Added support for HTTP BAN requests. - Fixed regex match condition for URL paths in HTTP PURGE requests. - Fixed mod_xvarnish failing to correct the RewriteCond HTTPS variable for some HTTP requests. - Resolved a problem that prevented the expiration of end-user Development Mode exclusion rules. Stable 0.30.7, 2017-03-09 Changes since 0.30.6: - Update Varnish Cache dependency to 4.1.5. Edge 0.32.1, 2017-03-09 - Fixes for HTTPS support and Hitch configuration. Release 0.32, 2017-02-23 No changes since Edge 0.31. Edge 0.31, 2017-02-22 - Fixed opted-in domain management via prompt and misc UI cleanup. - Fixed license activation required message not displaying on new installations. - Fixed header X-Forwarded-For in new HTTPS implementation for websites hosted behind SSL/TLS terminating load balancers (Cloudflare, Cloudfront, etc). Edge 0.31, 2017-02-20 This update has significant changes with respect to HTTPS, to resolve sporadic issues and also in preparation for HTTP/2. Please report any problems discovered. The initial update requires EPEL for the added Hitch dependency (yum update xvarnish --enablerepo=epel). - Initial stage of project rename from xVarnish to Cachewall. See our news! - Revamped WebHost Manager user interface. - Varnish Cache 4.1.5; loosened Varnish Cache version dependency. - Improved HTTPS support: Hitch updated to 1.4.4, removal of XVSSL service. This change requires mod_xvarnish to be enabled and loaded, otherwise the HTTPS feature will be disabled automatically. - Ability to exclude requests from the web application firewall (WAF). Example: xvctl excludes create --type=waf PATTERN - Improved flexibility of VCL request pattern matching via libvmod_header. - Removed deprecated request headers added by xVarnish: XV-Connecting-IP, XV-Real-IP-Source - Renamed xvctl excludes argument --return-action (-r) to --type (-t). - Ability to specify multiple Varnish Cache storage backend specifications via configuration. - Manage Opt-in Mode domains from the Dashboard. - Improved Real-time Requests chart and Varnish Cache statistics tracking backend. - Internal rework and cleanup. - Dozens of other minor, miscellaneous enhancements and bugfixes. Release 0.30.6, 2016-12-22 - Fixed redirect in WebHost Manager script addon_xvarnish.cgi for non-root users. Release 0.30.5, 2016-12-20 - Fixed large number of open files by healthcheck logging introduced in 0.30.2. This problem may lead to the healthcheck failing to run additional checks after multiple days, all users are recommended to update. Release 0.30.4, 2016-12-16 - Corrected permissions for mod_xvarnish httpd include file. Release 0.30.3, 2016-12-15 - Fixed possible unbound variable while listing exclusions after having removed all rules. Release 0.30.2, 2016-12-13 - Reliability improvements for xvbeat service handling and improved error logging and output. - Healthcheck log messages are now always prefixed by the respective module name. - Updated WAF traffic statistics (xvbeat) aggregation configuration. - Improved logging and output handling. - Miscellenous internal cleanup and reorganization. - Fixed cPanel tailwatchd program path. - Fixed error when the primary IP address cannot be determined using the cPanel mainip file. - Fixed HTTPS (xvssl) failing on systems with IPv6 disabled (ipv6.disable=1). Release 0.30.1, 2016-12-03 - Fixed hitch_online Healthcheck module failing port availability check. Release 0.30, 2016-12-02 - Update to Varnish Cache 4.1.4. (https://github.com/varnishcache/varnish-cache/blob/4.1/doc/changes.rst) - Better detection of LiteSpeed Web Server and whether it is enabled. - Fixes for HTTPS support (xvssl symlink target) in all environments (CentOS 6/7, EasyApache 3/4, LiteSpeed enabled/disabled). - xVarnish settings option "Reject Unrecognized Names" (hitch_enable_sni_noabort_match) is now disabled by default. ** - The system hostname certificate is now sent for visitor HTTPS requests which specify a name that wasn't found in any installed certificate. - Improvements and fixes fosyncsvnr upgrading xVarnish via the WebHost Manager plug-in or `xvctl check-updates|update`. - All Varnish Cache (varnishd) parameters may now be specified via xVarnish option varnishd_sysconfig_extra. - Fixed non-specific wildcard exclusion rules breaking exclusions. - Fixed xvbeat systemd service unit PIDFile. - Miscellaneous bugfixes. **: In the past xVarnish configured Hitch to reject HTTPS requests in this situation by default (e.g., ERR_SSL_UNRECOGNIZED_NAME_ALERT). If this is behavior desired, you may enable option "Reject Unrecognized Names" under Configuration > Hitch - HTTPS Frontend.