Information for: DEVELOPERS   PARTNERS   SUPPORT

Looking for something?

Custom Varnish configuration

This document contains information about custom Varnish configuration for Cloud Platform Enterprise applications.

Custom Varnish configurations are available only to Cloud Platform Enterprise subscriptions with dedicated load balancers. Site Factory and CDNs do not support custom Varnish configurations.

This documentation page describes the specific Varnish® configurations allowed in Cloud Platform.

Cloud Platform installs Varnish Cache, a caching reverse proxy, in front of all Cloud Platform load balancing infrastructure. To modify the behavior of Varnish, you must create a custom Varnish configuration using Varnish’s domain-specific programming language, VCL.

For more information about how Varnish caching benefits your website, see Using Varnish.

To deploy a custom Varnish configuration, contact Acquia Support. Acquia will provide you with a test environment for one week to test your new custom VCL. However, creating and testing the custom VCL is your responsibility.

Cloud Platform Enterprise customers must contact Acquia Support to create a support ticket to request a copy of the full VCL, based on their contractual NDA. Acquia does not disclose the configuration of our Nginx infrastructure, as the configuration is both proprietary and subject to change without notice. Acquia Support does not provide support for specific VCL customizations.

Allowed Varnish configuration use cases

The following are the only permitted use cases for custom Varnish configurations on Cloud Platform:

Custom Varnish configuration schedule

Acquia deploys custom Varnish configurations on a weekly schedule. To deploy your custom Varnish configuration, you must meet the following weekly schedule:

  1. Contact Acquia Support to determine if one of the allowed VCL modifications is an appropriate solution for your needs.

  2. Request a copy of your current VCL from Acquia.

  3. Supply Acquia the list of environments in front of which you want to place the test load balancer.

  4. You can choose to either supply a new VCL file, or request to reinstate the default Acquia VCL, by Monday at 12:00 PM Eastern Standard Time (EST) (convert to UTC).

    • If you choose to supply a new VCL file, you must supply the entire VCL file, and not only the lines you want to change.
    • If you choose to reinstate the default Acquia VCL, explicitly state this request in your Support ticket. You do not need to submit a VCL file in this case.

    Note

    VCL files on Cloud Platform must be less than 128 KB in size.

  5. Acquia deploys a test load balancer with the new VCL no later than 17:00 Eastern (North America) Time on Tuesday. After the load balancer is deployed, it is your responsibility to test that the new features work as desired. To test the VCL on the test load balancer, modify the hosts file on your local machine to point to the IP address of the test load balancer.

  6. If you encounter any issues requiring a revised VCL, you must submit a revised VCL no later than 09:00 Eastern (North America) Time on Wednesday for Acquia to apply the revised VCL to the test load balancer.

  7. You must complete any testing and confirm your approval no later than 15:00 Eastern (North America) Time on Wednesday.

  8. Acquia performs code reviews between 15:00 Eastern (North America) Time on Wednesday and 15:00 Eastern (North America) Time on Thursday.

  9. VCL updates restart Varnish and clear Varnish cache. To minimize disruption, Acquia releases VCL files during non-peak periods, according to the following schedule:

    Region Data centers Time
    Asia-Pacific and Japan * AP-southeast-2, AP-southeast-1, AP-northeast-1 19:00–20:00 UTC Thursday
    Europe and Africa EU-central-1, EU-west-1 04:00–05:00 UTC Friday
    Americas SA-east-1, US-east-1, CA-central-1, US-west-2 07:00–08:00 UTC Friday

    * Default window

    You must specify your preferred window in the Support ticket for the custom VCL update. After you test and approve the custom VCL, Acquia will add it to the tasks scheduled for that maintenance window.

Requirements for Simple Error Pages on Cloud Platform

Simple Error Pages (SEPs) provided in a custom VCL must meet the following criteria:

  • The file type must be HTML.
  • The file must be smaller than 10 KB in size.
  • The file cannot contain links to external files, such as style sheets or images. External files are frequently unavailable when the back end layers of the application are unresponsive.
  • The file must include the specific Varnish error code to simplify troubleshooting.

Customers must not send a complex snippet that includes unnecessary content such as entire headers and footers. The following is an example of a complex snippet received from the customer:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" /><meta http-equiv="X-UA-Compatible" content="IE=edge" /><meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>We've got some trouble | 503 - Webservice currently unavailable</title>
  <style type="text/css">/*! normalize.css v5.0.0 | MIT License | github.com/necolas/normalize.css */html{font-family:sans-serif;line-height:1.15;-ms-text-size-adjust:100%;-webkit-text-size-adjust:100%}body{margin:0}article,aside,footer,header,nav,section{display:block}h1{font-size:2em;margin:.67em 0}figcaption,figure,main{display:block}figure{margin:1em 40px}hr{box-sizing:content-box;height:0;overflow:visible}pre{font-family:monospace,monospace;font-size:1em}a{background-color:transparent;-webkit-text-decoration-skip:objects}a:active,a:hover{outline-width:0}abbr[title]{border-bottom:none;text-decoration:underline;text-decoration:underline dotted}b,strong{font-weight:inherit}b,strong{font-weight:bolder}code,kbd,samp{font-family:monospace,monospace;font-size:1em}dfn{font-style:italic}mark{background-color:#ff0;color:#000}small{font-size:80%}sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}sub{bottom:-.25em}sup{top:-.5em}audio,video{display:inline-block}audio:not([controls]){display:none;height:0}img{border-style:none}svg:not(:root){overflow:hidden}button,input,optgroup,select,textarea{font-family:sans-serif;font-size:100%;line-height:1.15;margin:0}button,input{overflow:visible}button,select{text-transform:none}[type=reset],[type=submit],button,html [type=button]{-webkit-appearance:button}[type=button]::-moz-focus-inner,[type=reset]::-moz-focus-inner,[type=submit]::-moz-focus-inner,button::-moz-focus-inner{border-style:none;padding:0}[type=button]:-moz-focusring,[type=reset]:-moz-focusring,[type=submit]:-moz-focusring,button:-moz-focusring{outline:1px dotted ButtonText}fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em}legend{box-sizing:border-box;color:inherit;display:table;max-width:100%;padding:0;white-space:normal}progress{display:inline-block;vertical-align:baseline}textarea{overflow:auto}[type=checkbox],[type=radio]{box-sizing:border-box;padding:0}[type=number]::-webkit-inner-spin-button,[type=number]::-webkit-outer-spin-button{height:auto}[type=search]{-webkit-appearance:textfield;outline-offset:-2px}[type=search]::-webkit-search-cancel-button,[type=search]::-webkit-search-decoration{-webkit-appearance:none}::-webkit-file-upload-button{-webkit-appearance:button;font:inherit}details,menu{display:block}summary{display:list-item}canvas{display:inline-block}template{display:none}[hidden]{display:none}/*! Simple HttpErrorPages | MIT X11 License | https://github.com/AndiDittrich/HttpErrorPages */body,html{width:100%;height:100%;background-color:#21232a}body{color:#fff;text-align:center;text-shadow:0 2px 4px rgba(0,0,0,.5);padding:0;min-height:100%;-webkit-box-shadow:inset 0 0 100px rgba(0,0,0,.8);box-shadow:inset 0 0 100px rgba(0,0,0,.8);display:table;font-family:"Open Sans",Arial,sans-serif}h1{font-family:inherit;font-weight:500;line-height:1.1;color:inherit;font-size:36px}h1 small{font-size:68%;font-weight:400;line-height:1;color:#777}a{text-decoration:none;color:#fff;font-size:inherit;border-bottom:dotted 1px #707070}.lead{color:silver;font-size:21px;line-height:1.4}.cover{display:table-cell;vertical-align:middle;padding:0 20px}footer{position:fixed;width:100%;height:40px;left:0;bottom:0;color:#a0a0a0;font-size:14px}</style>
</head>
<body>
  <div class="cover">
  <h1>Webservice currently unavailable <small>Error 503</small></h1><p class="lead">We&#39;ve got some trouble with our backend upstream cluster.<br />Our service team has been dispatched to bring it back online.</p></div>
  <footer><p>Technical Contact: <a href="mailto:[email protected]">[email protected]</a></p></footer>
</body>
</html>

Customized ACLs on Cloud Platform

Custom Varnish Access Control Lists (vACLs) provided as part of a custom VCL must have the following structure:

  • Multiple allowlist and denylist rules may be created for each application.
  • Individual rules may be applied to multiple domain names on multiple environments.
  • Access control rules must be organized by domain name, and must not reuse domain name references.
  • All IPv4 addresses must be requested from the customer.

Note

If a CDN is present, an Access Control List in a cVCL is not applied to cached traffic at the CDN level. If you have a CDN, ensure that you apply access restrictions through the CDN.

The following example procedure lists the steps to configure an ACL:

  1. In the VCL file, locate the following section:

    ########################################################### <-- keep this line
## CUSTOMIZABLE SECTION: Access Control List (ACL) ######## <-- keep this line
########################################################### <-- keep this line
# acl customername {                                        <-- uncomment + edit
#   "10.10.9.1";     /* Website developer Annie.       */   <-- uncomment + edit
#   "10.10.9.2";     /* Joe at Operations.             */   <-- uncomment + edit
#   "10.10.10.0"/24; /* Entire team of editors.        */   <-- uncomment + edit
#   ! "10.10.11.1";  /* Except Chris.                  */   <-- uncomment + edit
# }                                                         <-- uncomment
########################################################### <-- keep this line

  2. Uncomment the editable lines:

    ########################################################### <-- keep this line
## CUSTOMIZABLE SECTION: Access Control List (ACL) ######## <-- keep this line
########################################################### <-- keep this line
acl customername {
  "10.10.9.1";     /* Website developer Annie.       */
  "10.10.9.2";     /* Joe at Operations.             */
  "10.10.10.0"/24; /* Entire team of editors.        */
  ! "10.10.11.1";  /* Except Chris.                  */
}
########################################################### <-- keep this line

  3. Change the name of the ACL:

    acl MyCustomer {

  4. Replace the template IP addresses with the IPv4 addresses that you want to allow:

    "233.163.58.255";     /* Office HQ                */
"17.57.71.1";         /* European partner agency  */
"238.243.52.0"/24;    /* Address range CI tooling */

  5. In the VCL file, locate the enforcement section:

    #########################################################        <-- keep this line
## CUSTOMIZABLE SECTION: Access Control List (ACL) ######        <-- keep this line
#########################################################        <-- keep this line
# if (!req.http.X-Acquia-Request &&                              <-- uncomment
#     std.ip(req.http.client-ip, "127.0.0.2") !~ acquia_acls &&  <-- uncomment
#     std.ip(req.http.client-ip, "127.0.0.2") !~ aws_internal && <-- uncomment
#     std.ip(req.http.client-ip, "127.0.0.2") !~ customername) { <-- edit acl name
#     return (synth(404, "Not Found"));                          <-- uncomment
# }                                                              <-- uncomment
#########################################################        <-- keep this line

  6. Uncomment the code section:

    #########################################################        <-- keep this line
## CUSTOMIZABLE SECTION: Access Control List (ACL) ######        <-- keep this line
#########################################################        <-- keep this line
if (!req.http.X-Acquia-Request &&
    std.ip(req.http.client-ip, "127.0.0.2") !~ acquia_acls &&
    std.ip(req.http.client-ip, "127.0.0.2") !~ aws_internal &&
    std.ip(req.http.client-ip, "127.0.0.2") !~ customername) {
    return (synth(404, "Not Found"));
}
#########################################################        <-- keep this line

  7. In the std.ip(req.http.client-ip, "127.0.0.2") !~ customername) { line, replace the text customername with the ACL name that you defined earlier.

  8. Save the VCL file.

Database backups following the VCL access list update

After adding an access control list to your Varnish configuration file, you may not be able to download database backups through the Cloud user interface. It happens because while limiting access to your sites, your access control list also limits access to your Acquia default domain, such as example.prod.acquia-sites.com, that is required for database downloads to function.

To perform database backups:

  1. In the access control list of your VCL, add the IP addresses that can download backups.
  2. Perform database downloads through the Cloud API.

53 State Street, 10th Floor
Boston, MA 02109
United States
Phone: 888-922-7842