188 |
189 |
190 | "};
191 | return (deliver);
192 | }
193 |
194 | #######################################################################
195 | # Housekeeping
196 |
197 | sub vcl_init {
198 | }
199 |
200 | sub vcl_fini {
201 | return (ok);
202 | }
203 |
--------------------------------------------------------------------------------
/source/content/templates/vcl_defaultEE_andrew.vcl:
--------------------------------------------------------------------------------
1 | vcl 4.0;
2 |
3 | backend default {
4 | .host = "127.0.0.1"; # The domain or IP address of your ExpressionEngine Site
5 | .port = "8080"; # The port of your EE site. In production, Varnish should be on port 80, so consider changing your Apache server to port 8080
6 | .probe = {
7 | .url = "/";
8 | .timeout = 1000ms;
9 | .interval = 1s;
10 | .window = 10;
11 | .threshold = 8;
12 | }
13 | }
14 |
15 | sub vcl_recv {
16 |
17 | # Forward client's IP to backend
18 | unset req.http.X-Forwarded-For;
19 | set req.http.X-Forwarded-For = client.ip;
20 |
21 | # Set the URI of your system directory
22 | # In this example, we assume your admin interface is in "system", so just ensure it's right for your setup.
23 | if (req.url ~ "^/system/" ||
24 | req.url ~ "ACT=" ||
25 | req.method == "POST" ||
26 | (req.url ~ "member_box" && req.http.Cookie ~ "exp_sessionid"))
27 | {
28 | return (pass);
29 | }
30 |
31 | unset req.http.Cookie;
32 |
33 | # This is different, read this: https://www.varnish-software.com/blog/grace-varnish-4-stale-while-revalidate-semantics-varnish
34 | # set req.grace = 1h;
35 |
36 | return(hash);
37 | }
38 |
39 | sub vcl_backend_response {
40 |
41 | # Enable ESI includes
42 | set beresp.do_esi = true;
43 |
44 | # Our cache TTL
45 | set beresp.ttl = 1m;
46 |
47 | # set beresp.grace = 1h;
48 |
49 | return(deliver);
50 | }
51 |
--------------------------------------------------------------------------------
/source/content/templates/vcl_defaultEE_who.vcl:
--------------------------------------------------------------------------------
1 | backend default {
2 | .host = "127.0.0.1";
3 | .port = "80";
4 | .max_connections = 1024;
5 | }
6 |
7 | backend apache {
8 | .host = "127.0.0.1";
9 | .port = "8080";
10 | .max_connections = 1024;
11 | .first_byte_timeout = 300s;
12 | }
13 |
14 | acl purge {
15 | "localhost";
16 | }
17 |
18 | sub vcl_fetch{
19 |
20 | # strip the cookie before the image is inserted into cache.
21 | if (req.url~ "\.(png|gif|jpg|swf|css|js)$") {
22 | unset beresp.http.set-cookie;
23 | }
24 |
25 | ## Remove the X-Forwarded-For header if it exists.
26 | remove req.http.X-Forwarded-For;
27 |
28 | ## insert the client IP address as X-Forwarded-For. This is the normal IP address of the user.
29 | set req.http.X-Forwarded-For = req.http.rlnclientipaddr;
30 |
31 | // Dont cache 302 redirects and anything else other than what should be cached
32 | if (beresp.status!= 200 && beresp.status!= 404) {
33 | set beresp.ttl= 0s;
34 | return (deliver);
35 | }
36 |
37 | ## Deliver the content
38 | return(deliver);
39 | }
40 |
41 |
42 | ## Deliver
43 | sub vcl_deliver{
44 |
45 | ## We'll be hiding some headers added by Varnish. We want to make sure people are not seeing we're using Varnish.
46 | ## Since we're not caching (yet), why bother telling people we use it?
47 | remove resp.http.X-Varnish;
48 | remove resp.http.Via;
49 | remove resp.http.Age;
50 |
51 | ## We'd like to hide the X-Powered-By headers. Nobody has to know we can run PHP and have version xyz of it.
52 | remove resp.http.X-Powered-By;
53 |
54 | if (obj.hits> 0) {
55 | set resp.http.X-Cache = "HIT";
56 | } else {
57 | set resp.http.X-Cache = "MISS";
58 | }
59 |
60 | }
61 |
62 | sub vcl_recv{
63 |
64 | if (req.http.Host == "westeros.org" || req.http.Host == "www.westeros.org" || req.http.Host == "testsite.westeros.org" || req.http.Host ~ "hippokrene.com" || req.http.Host ~ "hippoiathanatoi.com" ) {
65 | set req.backend = apache;
66 | }
67 |
68 | if (req.http.Host ~ "hippoiathanatoi\.com") {
69 | return (pass);
70 | }
71 |
72 | remove req.http.X-Forwarded-For;
73 | if (req.http.CF-Connecting-IP) {
74 | set req.http.X-Forwarded-For = req.http.CF-Connecting-IP;
75 | } else {
76 | set req.http.X-Forwarded-For = client.ip;
77 | }
78 |
79 | ## We have to pipe file downloads or varnish may cut off long download times
80 | if (req.url~ "files") {
81 | return (pipe);
82 | }
83 |
84 | if (req.request == "PURGE") {
85 | if(!client.ip ~ purge) {
86 | error 405 "Not allowed.";
87 | }
88 | return (lookup);
89 | }
90 |
91 | set req.http.X-Device = "pc";
92 | if (req.http.User-Agent ~ "iPad" || req.http.User-Agent ~ "iP(hone|od)" || req.http.User-Agent ~ "Android" || req.http.User-Agent ~ "SymbianOS" || req.http.User-Agent ~ "^BlackBerry" || req.http.User-Agent ~ "^SonyEricsson" ||
93 | req.http.User-Agent ~ "^Nokia" || req.http.User-Agent ~ "^SAMSUNG" || req.http.User-Agent ~ "^LG")
94 | {
95 | set req.http.X-Device = "mobile";
96 | }
97 |
98 | if (req.request== "POST") {
99 | return (pass);
100 | }
101 |
102 | if (req.url~ "/server-status" ) {
103 | return (pass);
104 | }
105 |
106 | if (req.url~ "^/Scripts/ExpressionEngine/valyria" || req.url~ "ACT=") {
107 | return (pass);
108 | }
109 |
110 | if (req.url~ "(section=markasread|section=login|register)") {
111 | return (pass);
112 | }
113 | else {
114 | // Remove has_js and Google Analytics __* cookies.
115 | set req.http.Cookie = regsuball(req.http.Cookie, "(^|;\s*)(_[_a-z]+|has_js)=[^;]*", "");
116 | // Remove a ";" prefix, if present.
117 | set req.http.Cookie = regsub(req.http.Cookie, "^;\s*", "");
118 | if (req.http.cookie&& ((req.http.cookie~ "exp_sessionid") || (req.http.cookie~ "member_id" && req.http.cookie!~ "member_id=(0|-1)"))) {
119 |
120 | if (req.url~ "\.(png|gif|jpg|swf|css|js)$") {
121 | return(lookup);
122 | }
123 | else {
124 | return(pass);
125 | }
126 |
127 | }
128 | else {
129 | unset req.http.cookie;
130 | set req.grace= 15s;
131 | }
132 |
133 | }
134 |
135 | }
136 |
137 | sub vcl_hash{
138 |
139 | if (req.http.cookie&& (req.http.cookie~ "member_id"))
140 | {
141 | hash_data(regsuball(req.http.Cookie, "^.*;? ?PHPSESSID=([a-z0-9]+)( ?|;| ;).*$","\1"));
142 | }
143 |
144 | hash_data(req.http.host);
145 | hash_data(req.url);
146 | hash_data(req.http.X-Device);
147 |
148 | return (hash);
149 | }
150 |
151 | sub vcl_hit {
152 | if (req.request == "PURGE") {
153 | purge;
154 | error 200 "Purged.";
155 | }
156 | }
157 |
158 | sub vcl_miss {
159 | if (req.request == "PURGE") {
160 | purge;
161 | error 200 "Purged.";
162 | }
163 | }
164 |
165 | # source: https://justpaste.it/s86e
166 | # Created : 13th March 2016
167 | # Accessed: 16th August 2016
168 | # Posted by: https://ellislab.com/forums/member/18664/
169 | # varnish 3.0
170 |
--------------------------------------------------------------------------------
/source/content/templates/vcl_defaultMagento2_hummer.vcl:
--------------------------------------------------------------------------------
1 | vcl 4.0;
2 | ## source https://gist.github.com/hummer2k/6f32c489937f539f10ce collected: 16th August 2016
3 | import std;
4 | # The minimal Varnish version is 4.0
5 |
6 | backend default {
7 | .host = "{{ host }}";
8 | .port = "{{ port }}";
9 | }
10 |
11 | acl purge {
12 | {{ ips }}
13 | }
14 |
15 | sub vcl_recv {
16 | if (req.method == "PURGE") {
17 | if (client.ip !~ purge) {
18 | return (synth(405, "Method not allowed"));
19 | }
20 | if (!req.http.X-Magento-Tags-Pattern) {
21 | return (synth(400, "X-Magento-Tags-Pattern header required"));
22 | }
23 | ban("obj.http.X-Magento-Tags ~ " + req.http.X-Magento-Tags-Pattern);
24 | return (synth(200, "Purged"));
25 | }
26 |
27 | if (req.method != "GET" &&
28 | req.method != "HEAD" &&
29 | req.method != "PUT" &&
30 | req.method != "POST" &&
31 | req.method != "TRACE" &&
32 | req.method != "OPTIONS" &&
33 | req.method != "DELETE") {
34 | /* Non-RFC2616 or CONNECT which is weird. */
35 | return (pipe);
36 | }
37 |
38 | # We only deal with GET and HEAD by default
39 | if (req.method != "GET" && req.method != "HEAD") {
40 | return (pass);
41 | }
42 |
43 | return (hash);
44 | }
45 |
46 | sub vcl_hash {
47 | if (req.http.cookie ~ "X-Magento-Vary=") {
48 | hash_data(regsub(req.http.cookie, "^.*?X-Magento-Vary=([^;]+);*.*$", "\1"));
49 | }
50 | {{ design_exceptions_code }}
51 | }
52 |
53 | sub vcl_backend_response {
54 | if (beresp.http.content-type ~ "text") {
55 | set beresp.do_esi = true;
56 | }
57 |
58 | if (bereq.url ~ "\.js$" || beresp.http.content-type ~ "text") {
59 | set beresp.do_gzip = true;
60 | }
61 |
62 | # cache only successfully responses
63 | if (beresp.status != 200) {
64 | set beresp.ttl = 0s;
65 | set beresp.uncacheable = true;
66 | return (deliver);
67 | } elsif (beresp.http.Cache-Control ~ "private") {
68 | set beresp.uncacheable = true;
69 | set beresp.ttl = 120s;
70 | return (deliver);
71 | }
72 |
73 | if (beresp.http.X-Magento-Debug) {
74 | set beresp.http.X-Magento-Cache-Control = beresp.http.Cache-Control;
75 | }
76 |
77 | # validate if we need to cache it and prevent from setting cookie
78 | # images, css and js are cacheable by default so we have to remove cookie also
79 | if (beresp.ttl > 0s && (bereq.method == "GET" || bereq.method == "HEAD")) {
80 | unset beresp.http.set-cookie;
81 | if (bereq.url !~ "\.(css|js|jpg|png|gif|tiff|bmp|gz|tgz|bz2|tbz|mp3|ogg|svg|swf|woff)(\?|$)") {
82 | set beresp.http.Pragma = "no-cache";
83 | set beresp.http.Expires = "-1";
84 | set beresp.http.Cache-Control = "no-store, no-cache, must-revalidate, max-age=0";
85 | set beresp.grace = 1m;
86 | }
87 | }
88 | return (deliver);
89 | }
90 |
91 | sub vcl_deliver {
92 | if (resp.http.X-Magento-Debug) {
93 | if (obj.hits > 0) {
94 | set resp.http.X-Magento-Cache-Debug = "HIT";
95 | } else {
96 | set resp.http.X-Magento-Cache-Debug = "MISS";
97 | }
98 | } else {
99 | unset resp.http.Age;
100 | }
101 |
102 | unset resp.http.X-Magento-Debug;
103 | unset resp.http.X-Magento-Tags;
104 | unset resp.http.X-Powered-By;
105 | unset resp.http.Server;
106 | unset resp.http.X-Varnish;
107 | unset resp.http.Via;
108 | unset resp.http.Link;
109 | }
110 |
--------------------------------------------------------------------------------
/source/content/templates/vclex_startvarnish_debugmode~:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/varnish/varnish-wiki/da3fefba9048552a58cf11e1d97d84defa9ff0e0/source/content/templates/vclex_startvarnish_debugmode~
--------------------------------------------------------------------------------
/source/content/tutorials/aem.rst:
--------------------------------------------------------------------------------
1 | .. _aem:
2 |
3 | Adobe Experience Manager and Varnish
4 | ====================================
5 |
6 | Adobe Experience Manager (AEM) is an enterprise web content management system
7 | that facilitates organizing, managing, and delivering creative assets. It has
8 | ready-made templates that users can use to create content and store them securely
9 | in the cloud.
10 |
11 | Primarily, Adode recommends using the **Adobe Dispatcher** for caching pages. But,
12 | as well you may know, it is not flexible enough for the cache invalidation techniques
13 | needed today.
14 |
15 | Adobe Dispatcher
16 | -----------------
17 |
18 | It is relatively straightforward.
19 | It has built-in rules for invalidation.
20 | These specified rules are not flexible enough.
21 |
22 | Dispatcher limitations
23 | ......................
24 |
25 | - Caches documents as delivered in the AEM instance
26 | - **Does NOT cache** HTTP headers (which provide info on handling that content)
27 |
28 | - Holds onto the document
29 | - **Does NOT** hold onto the accompanying HTTP response
30 |
31 | This is where **VARNISH CACHE PLUS** can help in managing the complex rules
32 | needed for your site's cache invalidation.
33 |
34 |
35 | Varnish Cache Plus
36 | ------------------
37 |
38 | - Cache HTTP headers (requests and responses)
39 | - Configurable to cache any kind of HTTP request using queries
40 | - Cache re-directed responses thus reducing load on the machine
41 | - Querying of requests for content-heavy pages
42 | - ESI
43 | - Customization in flushing
44 |
45 | Vanish Cache is great if you run, for example, a social media, news, banking, or resource data site, among others. Of course, not all the features mentioned above are included in the Varnish community version – that's why we have Varnish Cache Plus.
46 |
47 | With Varnish Cache Plus, enhanced cache invalidation techniques you can employ include:
48 | - Users to purge content using key-based relationships
49 | - Scalable cache invalidation (increases cache hit-rate)
50 | - Exclude certain headers from cache
51 | - Invalidate page using *smart bans*
52 |
53 |
54 | Replacing Adobe Dispatcher with Varnish Cache Plus
55 | --------------------------------------------------
56 |
57 | Know this requires a user to have great understanding of Varnish and its
58 | language (VCL), AEM and HTTP. As challenging as it may be it is also rewarding
59 | to see your website fly.
60 |
61 | 1. The first rule of replacing Adobe Dispatcher with Varnish is to ensure that the VCL
62 | configuration file mimics the behavior of the dispatcher (an Apache module
63 | making use of CQ-handle headers to invalidate).
64 |
65 | 2. Any more site specific knowledge of the website layout can be used to limit
66 | the trees of invalidation more aggressively.
67 | More added value included read here `AEM - Cache Invalidation Part 2`_
68 |
69 | 3. Doing bans
70 | Your setup preference:
71 |
72 | - you can have Apache, Varnish and AEM on the same machine
73 |
74 | - you can have them on different machines and use the Varnish built-in
75 | SSL/TLS capabilities for handling both the request from the client
76 | and the backend.
77 |
78 |
79 | An example of excluding backend responses from cache-control
80 |
81 | .. literalinclude:: /content/examples/vcl_excludeFromCache.vcl
82 | :language: VCL
83 |
84 |
85 | An example of sending all traffic to vdir directory
86 |
87 | .. literalinclude:: /content/templates/vcl_defaultSample_mattias.vcl
88 | :language: VCL
89 | :lines: 64
90 |
91 |
92 | AEM resources
93 | -------------
94 |
95 | .. _`AEM - Cache Invalidation Part 1`: https://info.varnish-software.com/blog/advanced-cache-invalidation-applied-replacing-adobe-aem-cq5-dispatcher-with-varnish-plus-part-1
96 |
97 | .. _`AEM - Cache Invalidation Part 2`: https://info.varnish-software.com/blog/advanced-cache-invalidation-part2
98 |
--------------------------------------------------------------------------------
/source/content/tutorials/drupal/drupal_step_by_step.rst:
--------------------------------------------------------------------------------
1 | .. _drupal_step_by_step:
2 |
3 |
4 | Step-by-step guide to making your Drupal website fly
5 | ====================================================
6 |
7 | Let's go through some of the common steps required to install and configure Varnish
8 | and integrate it with Drupal to take your site to the next level.
9 |
10 | This article assumes that you have a running instance of Drupal and that you
11 | have administrator rights for said instance, both at the OS and application level.
12 | We have tested this using Ubuntu LTS 16.04, Varnish Cache 4.1 and Drupal 8.
13 |
14 | If you still need help Installing Drupal 8 visit the `Drupal-Site`_
15 |
16 | 1. Installing Varnish
17 | ---------------------
18 |
19 | In case you also do not have Varnish, you will need to follow the instructional
20 | section on how to :doc:`Install Varnish `
21 | before we can continue.
22 |
23 | .. _drupal_integration:
24 |
25 | 2. How to place Drupal 8 behind Varnish
26 | ---------------------------------------
27 |
28 | Now that you have set up Varnish in-front of your Drupal 8 installation, and
29 | have apache2 configured, you need to know how to configure Drupal to purge cached
30 | content. By default anonymous page caching is enabled.
31 |
32 | To configure caching in Drupal, log in as an administrator on your Drupal site.
33 |
34 | - Go to the Configuration Menu
35 | - Click on Performance
36 | - Locate Caching and check both the boxes
37 | x Cache pages for anonymous users (checked by default)
38 | x Cache blocks
39 | - Set the Minimum cache lifetime; ~ 60min
40 | - Set Expiration of cached pages; ~ 60min
41 |
42 | For Drupal's Performance settings go to `/admin/config/development/performance`.
43 |
44 | Set the value for 'Page cache maximum age' as shown below:
45 |
46 | .. image:: /image/1-set-page-cache-max-age.png
47 | :alt: Sphinx Neo-Hittite
48 | :align: center
49 | :width: 500px
50 |
51 | Always choose caching time keeping in mind both better site performance and the need
52 | to ensure that the cache is not stale for too long. This value will solely depend on the type of site
53 | you have, its content and what it purpose it serves.
54 |
55 | Drupal does two things:
56 |
57 | a. It sends the Purge-Cache-Tags header with every request,
58 | containing a space-separated list of all the page's cache tags.
59 | b. It also sends a BAN request with the appropriate cache tags whenever content
60 | or configuration is updated that should expire pages with the associated
61 | cache tags.
62 |
63 | Both of these can be achieved quickly and easily by enabling and configuring the
64 | `Purge` and `Generic HTTP Purger` modules. Read about the suggested plugins on
65 | on our main page.
66 |
67 | Next you need to add a 'purger' that will send the appropriate BAN requests
68 | using purge_purger_http: visit the Purge configuration page,
69 | `admin/config/development/performance/purge`,
70 |
71 | Then follow the steps below as in the image:
72 |
73 | i. Add a new purger
74 |
75 | .. image:: /image/2-add-purger.png
76 | :alt: Sphinx Neo-Hittite
77 | :align: center
78 | :width: 500px
79 |
80 |
81 | ii. Choose 'HTTP Purger' and click 'Add':
82 |
83 | .. image:: /image/3-http-purger.png
84 | :alt: Sphinx Neo-Hittite
85 | :align: center
86 | :width: 500px
87 |
88 |
89 | iii. Configure the Purger's name ("Varnish Purger"), Type ("Tag"), and Request
90 | settings (defaults for Drupal VM are hostname 127.0.0.1, port 81, path /,
91 | method BAN, and scheme http):
92 |
93 | .. image:: /image/4-http-purger-request.png
94 | :alt: Sphinx Neo-Hittite
95 | :align: center
96 | :width: 500px
97 |
98 | iv. Configure the Purger's headers (add one header Purge-Cache-Tags with the
99 | value [invalidation:expression]):
100 |
101 | .. image:: /image/5-http-purger-header-cache-tags.png
102 | :alt: Sphinx Neo-Hittite
103 | :align: center
104 | :width: 500px
105 |
106 | Note from the Original Author: **Don't use the header in the screenshot—use Purge-Cache-Tags!**
107 |
108 | Images and textual courtesy: `Jeff Geerling's Post on Drupal 8 and Varnish`
109 |
110 | - Lastly Save the configuration and test that Varnish is working.
111 | - Then move on to more advanced stuff; personalized caching is a recommendation.
112 |
113 | This is a basic configuration for Varnish and Drupal; to go into more depth, use VCL
114 | to write your own customized code. This wiki contains some templates and examples.
115 |
116 | 3. Caching
117 | ----------
118 |
119 | Varnish caches everything, so you need to write a rule to exclude what you do not
120 | want to cache.
121 |
122 | By default, Varnish caches two types of requests: GET and HEAD.
123 | Other requests like DELETE, POST and PUT are never cached. That means you do not
124 | have to worry about requests that make changes to data because they are allowed
125 | to get to the application.
126 |
127 | 4. Excluding URLS
128 | -----------------
129 |
130 | Pages protected using HTTP Authorization are never cached.
131 | For your application-specific mechanisms, you need to add a rule such as
132 | the following to ensure that login pages aren't cached.
133 |
134 | .. literalinclude:: /content/examples/drupal_exclude_url.vcl
135 | :language: VCL
136 |
137 | If we did end up caching login pages, we could end up serving the same content
138 | to all users, which brings us to our next topic: Cookies!
139 |
140 | 5. Cookies
141 | ----------
142 |
143 | Cookies are everywhere these days! And we need some of them.
144 | But they are also one of the most important things in the caching decision.
145 | Making a choice between which cookies to cache or include is very important for
146 | a web application.
147 |
148 | Examples such as your site statistics analysis or your website indexing require
149 | cookies too. But these are not used by your Drupal site at all but if they didn't
150 | exist on your site, your web content wouldn't be indexed for searches. Either way
151 | these cookies make your site's content uncacheable and therefore you as the developer
152 | have to make caching choices very carefully.
153 |
154 | On the other hand, cookies related to page designs and other static content need
155 | to be allowed to cache. Below is an example of caching cookies for your Drupal site:
156 |
157 | .. literalinclude:: /content/examples/vclex_drupal_cachecookies.vcl
158 | :language: VCL
159 |
160 | 6. Drupal Caching Headers
161 | -------------------------
162 |
163 | Drupal sends its own caching information in response headers just like many other
164 | web applciations. These headers are obviously important to your web application
165 | and if you configure your Varnish to never cache any response, this could destabilize
166 | your web application. So you need add some configurations to your VCL code that
167 | will cache your Drupal header responses but not cache other headers.
168 |
169 | 7. Purging
170 | ----------
171 |
172 | This bit of code is to govern which IP addresses can access the config files.
173 |
174 | .. literalinclude:: /content/examples/allow_purging.vcl
175 | :language: VCL
176 |
177 | 8. Restart services after making changes
178 | ----------------------------------------
179 |
180 | Don't forget to restart after making changes:
181 |
182 | .. literalinclude:: /content/examples/snippet2_restart_systemd
183 | :language: VCL
184 |
185 | 9. Go further
186 | -------------
187 |
188 | If you are interested in Varnish, you can always give Varnish Plus a go with a
189 | free trial. You can capture real-time traffic statistics,
190 | create a paywall for premium content, simultaneously work on administration
191 | across all Varnish servers, record relationships between web pages for easy
192 | content maintenance, detect devices used for browsing, accelerate APIs and more.
193 |
194 | .. _`Drupal-Site`: https://www.drupal.org/8
195 |
196 | .. _`Jeff Geerling's Post on Drupal 8 and Varnish`: http://www.jeffgeerling.com/blog/2016/use-drupal-8-cache-tags-varnish-and-purge
197 |
--------------------------------------------------------------------------------
/source/content/tutorials/drupal/index.rst:
--------------------------------------------------------------------------------
1 | .. _drupal:
2 |
3 |
4 | Drupal with Varnish
5 | ===================
6 |
7 | Drupal is an open source content managenment system (CMS) written in PHP.
8 |
9 | Varnish will help provide a smoother user interface for the potentially millions of
10 | users who access the site every day. Varnish will not only accelerate your website's
11 | performance but will also protect all of your Drupal websites against hackers and bots.
12 |
13 | The Drupal CMS is by default served simply and plainly and is mostly marketed to
14 | technical developers who use their share of CSS magic to make their website stand out.
15 |
16 | Drupal features awesome responsive themes, blog themes, e-commerce themes and more.
17 |
18 | Drupal is also SEO friendly and accounts for about 3% of all websites on
19 | the internet, of which many belong to high-profile, well-known clients.
20 |
21 | Drupal is used by multi-organizations, e-commerce sites, technology companies,
22 | scientists, celebrities, musicians, and everyone in between.
23 |
24 | Although Drupal has its own caching mechanism and stores data from multiple page
25 | levels, yet with all the traffic from potential clients and reckless hackers,
26 | Varnish can add an extra boost to your site's performance!
27 |
28 | Is your Drupal website slow? We think that with a little help in your configurations,
29 | your Drupal site can fly!
30 |
31 | Get Varnish!
32 |
33 | .. toctree::
34 | :hidden:
35 |
36 | drupal_step_by_step
37 | drupal_vcl
38 |
39 |
40 | Implementing Drupal 8 with Varnish
41 | ----------------------------------
42 |
43 | Varnish is easy to set up and use. Since we have an open source project you are
44 | always welcome to try our community edition and contribute your fair share
45 | of new libraries, plugins and features.
46 |
47 | So where in Drupal will you be using Varnish?
48 |
49 | Drupal as a content management system:
50 | - Stores its contents in a database (mostly a separate independent database with its own mind)
51 | - All data in a CMS is usually normalized across databases and servers.
52 | - The design is completely separate from all its contents.
53 |
54 | Drupal provides, advanced URL control, custom content types (e-commerce, blogs, tutorials, newspapers, etc.),
55 | revision control (various versions of the same page) and user management (community).
56 | This makes a content management system usable for non-technical and technical users alike.
57 | It also makes the websites highly scalable.
58 |
59 | To make a highly scalable website more manageable and provide better performance to end users,
60 | Varnish provides a number of services.
61 |
62 | Installation
63 | ------------
64 |
65 | If you are ready and just want to get started with the installation, go to:
66 |
67 | :ref:`Step by step Installation guide to make your website fly! `
68 |
69 | Please note that Drupal 8 supports;
70 |
71 | `varnish 3` and `varnish 4`.
72 |
73 | Each new upgrade includes a section about the changes that have been made.
74 |
75 | **We strongly recommend that you upgrade to Varnish 4 as we no longer provide support for Varnish 3.**
76 |
77 | To make your life easier, there is a script:
78 |
79 | VCL Migrator, which can help you upgrade from Varnish 3 to Varnish 4.
80 |
81 |
82 | Integration
83 | -----------
84 |
85 | Once you have your Varnish installed and configured, you will want to integrate
86 | it with your Drupal 8 installation.
87 |
88 | For Drupal's Performance settings go to `/admin/config/development/performance`.
89 |
90 | In Drupal 8, anonymous page caching is enabled by default.
91 |
92 | To disable caching, set the "Page cache maximum age" to no caching.
93 |
94 | See :ref:`How to place Drupal 8 behind Varnish `
95 |
96 | Drupal 8 removed the "Cache Blocks" and "Minimum Cache Lifetime" settings.
97 |
98 | Block caching is now set through each individual block's configuration.
99 | The master listing of blocks is found at /admin/structure/block.
100 |
101 |
102 | Our most recommended `Drupal Modules` for Varnish
103 | -------------------------------------------------
104 |
105 | 1. `Generic HTTP Purger`_
106 |
107 |
108 | 2. `Purge`_
109 |
110 | Purge automatically sets the http.response.debug_cacheability_headers property
111 | to true via it's purge.services.yml
112 |
113 | Drupal resources
114 | ----------------
115 |
116 | `Whole new Drupal-Varnish Configuration`_
117 |
118 | `Jeff Geerling's Post on Drupal 8 and Varnish`_
119 |
120 | `Caching Overview from Drupal`_
121 |
122 | `Drupal 8 Cache`_
123 |
124 | `Managing Project with Varnish`_
125 |
126 | `Varnish for beginners`_
127 |
128 | `Configuring Varnish 3 for Drupal 7`_
129 |
130 |
131 | .. _`Jeff Geerling's Post on Drupal 8 and Varnish`: http://www.jeffgeerling.com/blog/2016/use-drupal-8-cache-tags-varnish-and-purge
132 |
133 | .. _`Caching Overview from Drupal`: https://www.drupal.org/docs/7/managing-site-performance-and-scalability/caching-to-improve-performance/caching-overview
134 |
135 | .. _`Whole new Drupal-Varnish Configuration`: https://www.drupal.org/docs/7/caching-to-improve-performance/varnish-cache
136 |
137 | .. _`Varnish for beginners`: https://dev.acquia.com/blog/explaining-varnish-beginners
138 |
139 | .. _`Managing Project with Varnish`: https://www.drupal.org/project/varnish
140 |
141 | .. _`Configuring Varnish 3 for Drupal 7`: https://fourkitchens.atlassian.net/wiki/display/TECH/Configure+Varnish+3+for+Drupal+7
142 |
143 | .. _`Drupal 8 Cache`: https://pantheon.io/docs/drupal-8-cache/
144 |
145 | .. _`Purge`: https://www.drupal.org/project/purge
146 |
147 | .. _`Generic HTTP Purger`: https://www.drupal.org/project/purge_purger_http
148 |
--------------------------------------------------------------------------------
/source/content/tutorials/expressionEngine.rst:
--------------------------------------------------------------------------------
1 | .. _expressionEngine:
2 |
3 |
4 | ExpressionEngine and Varnish
5 | =============================
6 |
7 | ExpressionEngine is another powerful digital content delivery platform from the
8 | creator of CodeIgniter (agile, open-source framework).
9 |
10 |
11 | Resources
12 | .........
13 |
14 | Making ExpressionEngine Sites Fly with Varnish: https://ellislab.com/blog/entry/making-sites-fly-with-varnish
15 | (This post is for Varnish 3 configuration; other than that, it's a great explanation to move forward.)
16 |
17 | Controlling the cache using ESI: https://www.smashingmagazine.com/2015/02/using-edge-side-includes-in-varnish/
18 |
19 | Server security issues: https://ellislab.com/blog/entry/http-host-and-server-name-security-issues
20 |
21 |
22 | A sample default VCL for ExpressionEngine
23 | ..........................................
24 |
25 | .. literalinclude:: /content/templates/vcl_defaultEE_andrew.vcl
26 | :language: VCL
27 |
28 |
29 |
30 | Source: https://gist.github.com/andrewfairlie/72f42dcdaacc8faaf1da
31 |
32 | Collected: 16th August 2016
33 |
--------------------------------------------------------------------------------
/source/content/tutorials/magento2/index.rst:
--------------------------------------------------------------------------------
1 | .. _magento2:
2 |
3 | Magento2 with Varnish
4 | =====================
5 |
6 | .. toctree::
7 | :hidden:
8 |
9 | magento2_varnish_basics
10 | m2_step_by_step
11 | magento1x
12 | magento2_vcl
13 |
14 |
15 | Magento is a powerful e-commerce platform for marketing, catalog management
16 | and search engine optimization. Magento provides online merchants with a flexible
17 | shopping cart system, control over a user-friendly WUI with content and various
18 | functionality for online users.
19 |
20 | Magento sites often use Varnish because it adds significant speed to websites.
21 | Varnish is one of the most cost-effective alternatives for web accelaration, offering
22 | a powerful return on investment. With a proper setup of Varnish,
23 | maintenance costs can be reduced by 85%.
24 |
25 | Magento2, with all its useful features, can be very demanding with resources and
26 | thus will likely deliver poor performance as clients increase. With the latest
27 | release of Magento2, Varnish has been included as a requirement, as it will
28 | help the site fly with significant speed advantages!
29 |
30 | - Varnish can detect devices and thus provide device-specific services.
31 |
32 | - It allows modification of cache control headers
33 |
34 | - Write caching based on your own caching policies, such as stripping cookies,
35 | overriding caching time, setting which pages to cache or not, and much more.
36 |
37 | To read more about installing `Magento 2`_
38 |
39 | Implementing Magento 2 with Varnish
40 | -----------------------------------
41 |
42 | Magento itself has a caching mechanism, but it does not cache pages.
43 | But Magento2 supports Varnish Cache out of the box.
44 | In order to run Varnish on your Magento2 implementation all you need to do
45 | is install Varnish and deploy the Varnish configuration file (A Varnish VCL file)
46 | in your Varnish implementation.
47 |
48 | To read more on the basics of how Varnish works with Magento2, go to
49 |
50 | :ref:`Magento 2 and Varnish Basics `
51 |
52 | If you are ready and just want to get started with the installation go to:
53 |
54 | :ref:`Step by step Installation guide to make your website fly! `
55 |
56 | Please note that Magento2 supports:
57 |
58 | `varnish 3` and `varnish 4` out of the box.
59 |
60 | Each new upgrade includes a section about the changes that have been made.
61 |
62 | **We strongly recommend that you upgrade to Varnish 4 as we no longer provide support for Varnish 3.**
63 |
64 | To make your life easier, there is a script:
65 |
66 | VCL Migrator, which can help you upgrade from Varnish 3 to Varnish 4.
67 |
68 | .. _magento2_resources:
69 |
70 | Magento 2 resources
71 | -------------------
72 |
73 | `Magento Installation`_
74 |
75 | `Quick Install Magento2`_
76 |
77 | `Configuring and Use Varnish with Magento`
78 |
79 | `Magento and Cache Clearning`_
80 |
81 | `How Varnish Caching works`_
82 |
83 | `Magento, Varnish and Turpentine`_
84 |
85 | `A Magento-Varnish Repo`_
86 |
87 | `Magento Stackexchage`_
88 |
89 | .. _`Magento 2`: http://devdocs.magento.com/guides/v2.1/install-gde/bk-install-guide.html
90 | .. _`Magento Installation`: http://devdocs.magento.com/guides/v2.1/install-gde/bk-install-guide.html
91 | .. _`Configuring and Use Varnish with Magento`: http://devdocs.magento.com/guides/v2.0/config-guide/varnish/config-varnish.html
92 | .. _`Magento and Cache Clearning`: http://devdocs.magento.com/guides/v2.0/config-guide/varnish/use-varnish-cache.html
93 | .. _`How Varnish Caching works`: http://devdocs.magento.com/guides/v2.0/config-guide/varnish/use-varnish-cache-how.html
94 | .. _`Magento, Varnish and Turpentine`: https://www.magentocommerce.com/magento-connect/turpentine-varnish-cache.html
95 | .. _`A Magento-Varnish Repo`: https://github.com/huguesalary/Magento-Varnish
96 | .. _`Quick Install Magento2`: http://devdocs.magento.com/guides/v2.1/install-gde/install-quick-ref.html
97 | .. _`Magento Stackexchage`: http://magento.stackexchange.com/questions/91087/magento-2-admin-url-not-working-and-loaded-frontend-is-all-messy
98 |
--------------------------------------------------------------------------------
/source/content/tutorials/magento2/m2_step_by_step.rst:
--------------------------------------------------------------------------------
1 | .. _m2_step_by_step:
2 |
3 | Step-by-step guide to making your Magento2 website fly
4 | =======================================================
5 |
6 | Magento2 is a PHP-based e-commerce platform.
7 | There are two editions:
8 |
9 | - Community edition (CE)
10 |
11 | - Enterprise edition (EE)
12 |
13 | Whichever works best for you, you do of course want to get started with a performance increase for
14 | your website right away!
15 |
16 | Let's get started!
17 |
18 | This article assumes that you have a running instance of Magento2 and that you
19 | have administrator rights for said instance, both at the OS and application level.
20 | We have tested this using Ubuntu LTS 16.04, Varnish Cache 4.1 and Magento2.
21 |
22 | If you need guidance on the installation of Magento, please visit the `Magento-Site`_
23 |
24 |
25 | 1. Installing Varnish
26 | ---------------------
27 |
28 | In case you also do not have Varnish, you will need to follow the instructional
29 | section on how to :doc:`Install Varnish `
30 | before we can continue.
31 |
32 | 2. How to place Magento2 behind Varnish
33 | -----------------------------------------
34 |
35 | Here we discuss how to configure your Magento2 behind Varnish. The Magento2 admin
36 | states that the built-in application cache is not recommended for production use,
37 | but that does not mean that Varnish is already configured. Varnish needs to be installed
38 | and the configuration file suitably configured and deployed.
39 |
40 | We assume that you have Magento2 installed and running on your backend servers
41 | and that your server is a Debian-based Linux server.
42 |
43 | Configuring Magento
44 | ...................
45 |
46 | 1. Visit the Magento2 admin page and go to:
47 |
48 | - > Stores
49 | - > Advanced
50 | - > System
51 | - > Full Page Cache
52 |
53 | Here switch caching application to **Varnish**
54 |
55 | This is what the Magento2 mdmin page should look like:
56 |
57 | .. image:: /image/config_varnish_admin.png
58 | :alt: Sphinx Neo-Hittite
59 | :align: center
60 | :width: 500px
61 |
62 | Image courtesy: `Magento Site`_
63 |
64 | 2. Configuring for Varnish
65 |
66 | - Under the Additional section, find a button for exporting the ready-made configuration file for Varnish 3 or 4. We recommend you use Varnish 4, as earlier versions are no longer supported.
67 |
68 | Click on::
69 | -> Export VCL for Varnish 4
70 | This is usually named varnish.vcl
71 |
72 | Place the file in a Varnish folder for configuration (any place that is safe for you).
73 |
74 | - Next, to add Varnish repository, follow the instructions at :ref:`Install Varnish `
75 |
76 | 3. Testing your setup
77 |
78 | Now check if your services are up and running:
79 |
80 | ``$ ps -e | grep 'apache2|varnish'``
81 |
82 | If you receive outputs like the ones below::
83 |
84 | 1143 ? 00:00:03 varnishd
85 | 1148 ? 00:00:17 varnishd
86 | 1366 ? 00:02:02 varnishlog
87 | 1591 ? 00:00:01 apache2
88 | 11743 ? 00:00:10 apache2
89 | 11744 ? 00:00:10 apache2
90 |
91 | Congratulations! You have your services running on the backend.
92 |
93 | Now we need to check the Magento2 frontend:
94 | As you may have already noticed above, there is a ``varnishlog`` process running as well.
95 |
96 | 3. Restarting services after making changes
97 | --------------------------------------------
98 |
99 | .. literalinclude:: /content/examples/snippet2_restart_systemd
100 | :language: VCL
101 |
102 | 4. Basic caching
103 | ----------------
104 |
105 | Varnish does not cache cookies or their headers. But some cookies are marked as safe
106 | by the Magento site. Therefore it is recommended to remove or ignore these cookies
107 | so that Varnish can cache anything.
108 |
109 | An example, such as the following, will help to unset/remove unwanted cookies.
110 |
111 | Update your `default.vcl` with this code or a similar code of your choice.
112 |
113 | Under the `vcl_recv` add the following code.
114 |
115 | Warning: Make sure to add the code below the default code given for `vcl_recv`
116 |
117 | .. literalinclude:: /content/examples/snippet3_remove_cookies
118 | :language: VCL
119 |
120 | 5. Excluding certain URLs
121 | -------------------------
122 |
123 | Not all URLs should be cached. Especially not in sites that deal with personal
124 | information such as credit cards or financial details.
125 |
126 | .. literalinclude:: /content/examples/m2_exclude_url.vcl
127 | :language: VCL
128 |
129 | 6. Extended caching
130 | -------------------
131 |
132 | There is a subroutine called *vcl_fetch* which is by default set to 120 seconds
133 | as can be seen. You can extend this caching value by:
134 |
135 | .. literalinclude:: /content/examples/vcl_fetch.vcl
136 | :language: VCL
137 |
138 | This sets the TTL to 5 seconds, making Varnish pick up changes every 5 seconds.
139 | Add this subroutine right below the *backend default*.
140 |
141 | However, there is a downside to short TTL values in that they increase the load
142 | not only on the backend servers but also on frontend servers. Of course this
143 | gives you a better control over your cache, but it also increases overheads, such
144 | as network traffic, slower response times, which diminish the whole
145 | purpose of Varnish.
146 |
147 | Decreasing TTL values is not a good solution for high-traffic servers.
148 | Varnish has a better solution for that.
149 |
150 | 7. Specific TTL-based caching
151 | -----------------------------
152 |
153 | Varnish creates a TTL value for every object in the cache. The most effective way
154 | of increasing a website's hit ratio is to increase the time-to-live (TTL) of the
155 | objects.
156 |
157 | 8. Go further
158 | --------------
159 |
160 | If you are interested in Varnish, you can always give Varnish Plus a go with a free trial.
161 | You can capture real-time traffic statistics,
162 | create a paywall for premium content, simultaneously work on administration
163 | across all Varnish servers, record relationships between web pages for easy
164 | content maintenance, detect devices used for browsing, accelerate APIs and more.
165 |
166 | Check out the links below to take your Varnish-Magento site to new performance heights.
167 |
168 | 9. For more guidance
169 | ---------------------
170 |
171 | You can always refer to the `Configure and Use Varnish `_
172 | at the Magento site.
173 |
174 | To see the guide on installing and configuring Magento with Varnish on web servers,
175 | please look at `here `_.
176 |
177 | If you are interested in trying out an installation try downloading Marko's
178 | Vagrant Box `marko_magento2github`_.
179 | His installation used nginx with Varnish and Magento. You can also read more
180 | about in Marko's blog post about placing Magento2 behind Varnish `marko_magento2post`_.
181 |
182 |
183 | .. _marko_magento2github: https://github.com/Marko-M/magento2-vagrant-nux
184 |
185 | .. _marko_magento2post: http://www.techytalk.info/magento-2-behind-varnish-reverse-proxy/
186 |
187 | .. _`Magento Site`: https://devdocs.magento.com/guides/v2.0/config-guide/varnish/config-varnish.html
188 |
189 | .. _`Magento-Site`: http://devdocs.magento.com/guides/v2.1/install-gde/bk-install-guide.html
190 |
--------------------------------------------------------------------------------
/source/content/tutorials/magento2/magento1x.rst:
--------------------------------------------------------------------------------
1 | .. _magento1x:
2 |
3 | Varnish with Magento 1.9 and older
4 | ==================================
5 |
6 | Magento versions 1.9 and earlier did not include built-in support for Varnish.
7 |
8 | Until version 1.9.x Magento provided an extension named `Turpentine`_, which improved
9 | Magento's compatibility with Varnish. Turpentine is a Magento extension that provides
10 | pre-configured Varnish Configuration (VCL) files that can significantly improve
11 | the cache-hit rate.
12 |
13 | There is a `Github Repo for Magento Turpentine` developed by `Nexcess.net`.
14 |
15 | Quoting from the Magento commerce site:
16 |
17 | "Note that while this extension is now considered stable, it is strongly
18 | recommended that it be tested on a development/staging site before deploying on
19 | a production site due to the potential need to add custom ESI policies for
20 | blocks added by other extensions."
21 |
22 | .. _`Turpentine`: https://www.magentocommerce.com/magento-connect/turpentine-varnish-cache.html
23 | .. _`Github Repo for Magento Turpentine`: https://github.com/nexcess/magento-turpentine
24 |
25 | Magento 1.x step-by-step guide
26 | ------------------------------
27 |
28 | Please note that at this time, Magento2 is the latest version.
29 | Upgrading to the latest version of Magento2 is recommended.
30 |
31 | However if for whatever reason you choose to continue to use Magento 1.x, bear in
32 | mind that Magento 1.x does not offer out-of-the-box Varnish support, but
33 | there are plugins that can help your Varnish configurations with Magento 1.x.
34 |
35 | Magento 1.9 and older resources
36 | -------------------------------
37 |
38 | `Magento1.9 Official Docs`_
39 |
40 | .. _`Magento1.9 Official Docs`: http://devdocs.magento.com/guides/m1x/ce19-ee114-home.html
41 |
--------------------------------------------------------------------------------
/source/content/tutorials/magento2/magento2_varnish_basics.rst:
--------------------------------------------------------------------------------
1 | .. _magento2_varnish_basics:
2 |
3 | Understanding Magento2 and Varnish
4 | ===================================
5 |
6 | This chapter is mainly written for web developers who want to get a clear idea
7 | about the basics of using Varnish with Magento.
8 |
9 | Varnish, as you may already know, is designed for HTTP semantics and will soon be
10 | available for HTTP/2. The new version of HTTP/2 has been released under `RFC 7540`_.
11 | However one must know that HTTP/2 is an alternative to HTTP/1.1 and does not
12 | outmode HTTP/1.0.
13 |
14 | This protocol allows for any given website to send multiple requests in
15 | serial mode over a single connection so that when a single client wants to fetch
16 | several resources in parallel, it can just open several connections to fetch from
17 | a single web server.
18 |
19 | Now imagine multiple customers trying to order several products in parallel from
20 | a single Magento web server. The overhead this may cause is vast and potentially crippling,
21 | which is why adding Varnish to the mix can save the day!
22 |
23 | To learn more about the basics of HTTP visit `HTTP Basics`_ at the `Varnish Software website`.
24 |
25 | You also need to be clear about what you want Varnish to do for your website.
26 | While analyzing and learning to understand your website, ask yourself the following questions:
27 |
28 | - What makes the pages on your Magento website different from each other?
29 | - Do differences apply to entire pages or just parts of them?
30 | - How should I inform Varnish about the differences?
31 |
32 | To answer all your questions, follow the link to our Varnish book discussing
33 | `Content Composition`_ .
34 |
35 | As you will see, Varnish can help manage your Magento website in more ways than one.
36 | Varnish can help your web servers with load balancing, firewalls, file compressions,
37 | cookie management, etc.
38 |
39 | Better insight on some of these Varnish features would be to get to know
40 | our product, Varnish Cache, a little better. Varnish Cache, as the name suggests,
41 | allows caching of resources. This mechanism is enhanced to allow multiple
42 | identical requests from different clients to have the
43 | same effect on a single request called the idempotency. But do not worry!
44 |
45 | Varnish Cache, if configured properly, does not cache `everything`! In fact you can
46 | decide what, how and when to cache. To be able to better manage
47 | the cache headers, one must understand the `cache related header fields of HTTP`.
48 | Varnish uses these rfc7232 and these rfc7234 cache header fields to decide which
49 | objects to cache.
50 |
51 | If a matched cache is valid then Varnish retrieves responses from the cache.
52 | This reduces the load on the origin server further (apart from Varnish's
53 | load-balancing capacities) from managing similar responses multiple times.
54 |
55 | When does Varnish serve the cached objects?
56 | -------------------------------------------
57 |
58 | In simple terms, Varnish serves cached content based on three things:
59 |
60 | 1. Cache matching
61 | 2. Allowance
62 | 3. Freshness of data
63 |
64 |
65 | 1. Cache matching
66 | .................
67 |
68 | The cached object is properly matched, which is called a `cache-hit`.
69 | An example of a cached object on a Magento site would be common product
70 | descriptions, but the price is not cached because price may vary over time.
71 | A cache-hit object is served without contacting the origin server. However if the
72 | object requested is not in cache then it's a `cache-miss` and in this case Varnish
73 | forwards this request to the origin serer.
74 |
75 |
76 | 2. Allowance
77 | ............
78 |
79 | As mentioned in the Varnish book, allowance is the validation of the `cache-hit`.
80 | Varnish also offers the option for users to choose how long an object should be in
81 | cache and when to serve from the cache and when not to as well as whether a cached object should
82 | be reserved or not. This validation process is done by checking whether the
83 | request contains the `no-cache` directive. In such a cache the HTTP Cache-Control
84 | header is checked for the presence of `no-cache`.
85 |
86 | Read more about the `Cache-Control header`_ in the Varnish book.
87 |
88 |
89 | 3.Freshness of data
90 | ...................
91 |
92 | When deciding whether to use a cached object, i.e whether to `allow`
93 | it, checking the freshness of the data and evaluating whether to deliver an
94 | expired object or not is the question.
95 |
96 | There are two kinds of objects:
97 |
98 | `fresh objects` - age has not exceeded hthe freshness lifetime
99 | `stale objects` - age has exceeded the freshness lifetime, i.e. it is now an
100 | `expired object`.
101 |
102 | To read more about how the freshness of an object is determined, visit the
103 | Varnish book, `Freshness`_ section.
104 |
105 | Now let's move on to understanding the `Caching system in Magento 2 `.
106 |
107 | .. _magento2_ce:
108 |
109 | Caching in Magento2
110 | --------------------
111 |
112 | Magento2 is the next-generation open source digital
113 | commerce platform. A large number of websites use Magento and with Magento2
114 | the server performance is boosted to a new level.
115 |
116 | Why does Magento2 require Varnish caching?
117 | ..............................................
118 |
119 | Magento websites are expected to have large amount of traffic. For the website
120 | to fly, Varnish Cache provides a caching mechanism that not only helps with
121 | caching but also provides other services that enable Magento web servers to
122 | provide excellent services to clients.
123 |
124 | Cache extensions
125 | ----------------
126 |
127 | Magento has two cache extensions:
128 |
129 | - The internal cache (filesystem)
130 |
131 | - The external cache (varnish!)
132 |
133 | Here we will mainly talk about Varnish, the external cache.
134 |
135 | As you may already know Magento2 supports Varnish out of the box.
136 | Varnish Cache is installed as an independent component. It serves as an
137 | intermediary between the web servers running Magento and the backened memory.
138 |
139 | Varnish Cache on a Magento2 site caches all/if any static pages and also parts
140 | of dynamic pages.
141 |
142 | Remember that Varnish has a lot of resources and but if you have any questions
143 | please feel free to contact us.
144 |
145 | .. _`HTTP Basics`: http://book.varnish-software.com/4.0/chapters/HTTP.html#resources-and-representations
146 | .. _`cache related header fields of HTTP`: http://book.varnish-software.com/4.0/chapters/HTTP.html#cache-related-headers-fields
147 | .. _`Freshness`: http://book.varnish-software.com/4.0/chapters/HTTP.html#freshness
148 | .. _`Cache-Control header`: http://book.varnish-software.com/4.0/chapters/HTTP.html#cache-control
149 | .. _`Content Composition`: http://book.varnish-software.com/4.0/chapters/Content_Composition.html
150 | .. _`RFC 7540`: https://www.rfc-editor.org/rfc/rfc7540.txt
151 |
--------------------------------------------------------------------------------
/source/content/tutorials/magento2/magento2_vcl.rst:
--------------------------------------------------------------------------------
1 | .. _magento2_vcl:
2 |
3 | Some sample VCL for Magento2
4 | ============================
5 |
6 | Purging Magento2 pages
7 | ......................
8 |
9 | .. literalinclude:: /content/templates/vcl_defaultMagento2_hummer.vcl
10 | :language: VCL
11 | :lines: 15,16-25,44
12 |
13 |
14 | Dealing with Magento-Vary header
15 | ................................
16 |
17 | .. literalinclude:: /content/templates/vcl_defaultMagento2_hummer.vcl
18 | :language: VCL
19 | :lines: 46-51
20 |
21 | Managing HIT and MISS
22 | ......................
23 |
24 | .. literalinclude:: /content/templates/vcl_defaultMagento2_hummer.vcl
25 | :language: VCL
26 | :lines: 91-109
27 |
28 | ESI
29 | ...
30 |
31 | .. literalinclude:: /content/templates/vcl_defaultMagento2_hummer.vcl
32 | :language: VCL
33 | :lines: 53,54-56,89
34 |
35 | GZIP
36 | ....
37 |
38 | .. literalinclude:: /content/templates/vcl_defaultMagento2_hummer.vcl
39 | :language: VCL
40 | :lines: 15,58-60,44
41 |
42 | Cache only successful responses
43 | ...............................
44 |
45 | .. literalinclude:: /content/templates/vcl_defaultMagento2_hummer.vcl
46 | :language: VCL
47 | :lines: 15,63-71,44
48 |
49 | Setting debug mode for cache cache-control
50 | ..........................................
51 |
52 | .. literalinclude:: /content/templates/vcl_defaultMagento2_hummer.vcl
53 | :language: VCL
54 | :lines: 15,73-75,44
55 |
56 | Remove unused cookies
57 | ......................
58 |
59 | .. literalinclude:: /content/templates/vcl_defaultMagento2_hummer.vcl
60 | :language: VCL
61 | :lines: 15,77-87,44
62 |
--------------------------------------------------------------------------------
/source/content/tutorials/sitecoreCMS.rst:
--------------------------------------------------------------------------------
1 | .. _sitecoreCMS:
2 |
3 |
4 | Sitecore CMS and Varnish
5 | ========================
6 |
7 | Sitecore is an enterprise-level content management system (CMS) built on ASP.NET.
8 | It is used worldwide for personal websites, blogging, e-commerce, etc.
9 |
10 |
11 |
12 | Resources
13 | ---------
14 |
15 | https://github.com/ClearPeopleLtd/ClearPeople.VarnishPurge
16 | (not updated in 2 years)
17 |
--------------------------------------------------------------------------------
/source/content/tutorials/varnish/builtin_vcl.rst:
--------------------------------------------------------------------------------
1 | .. _builtin_vcl:
2 |
3 | What's in the built-in VCL?
4 | ===========================
5 |
6 | .. literalinclude:: /content/templates/builtin.vcl
7 | :language: VCL
8 | :lines: 41-202
9 |
10 | An overview of the built-in VCL
11 | ...............................
12 |
13 | This is the built-in VCL that comes with your Varnish installation.
14 | This is also the VCL configuration Varnish automatically appends to your VCL
15 | file during compilation/loading.
16 |
17 | Collected on: 16th August 2016
18 |
19 | Source: https://github.com/varnishcache/varnish-cache/blob/master/bin/varnishd/builtin.vcl
20 |
--------------------------------------------------------------------------------
/source/content/tutorials/varnish/index.rst:
--------------------------------------------------------------------------------
1 | .. _varnish:
2 |
3 | Use Varnish on your Website
4 | ===========================
5 |
6 | .. toctree::
7 | :hidden:
8 |
9 | builtin_vcl
10 | multiple_varnishes
11 | run_varnish
12 | sample_vclTemplate
13 | troubleshooting_varnish
14 | varnish_ubuntu
15 | varnish_test
16 | varnishCacheVersions
17 | vcl
18 | vcl_examples
19 |
20 | Varnish can cache any web based content, meaning any CMS, intranet, ReST/Web API,
21 | or Streaming media content can literally gain performance increases in the range
22 | of 300-1000x times compared to what standard web servers can provide.
23 |
24 | But, before you get to Varnish, You want to **get Varnish**. You have two choices:
25 |
26 | - Install **binary packages**
27 | - Compile it yourself from **source code**
28 |
29 | We have packages for a number of operating systems, and we have the open source
30 | project available on Github.
31 |
32 | If you plan to subscribe to Varnish Plus, check out `products at our website`_
33 |
34 |
35 | **Installing Varnish with binary packages**
36 | -------------------------------------------
37 |
38 | To just get started with installation on your machine:
39 |
40 | Requirements
41 | ............
42 |
43 | Your choice of operating system, preferably UNIX.
44 | Below we have some helpful commands to get you started with your choice of OS.
45 |
46 | Choosing OS
47 | -----------
48 |
49 | FreeBSD
50 | .......
51 |
52 | Binary package:
53 |
54 | .. code-block:: bash
55 |
56 | pkg_add -r varnish
57 |
58 | From source:
59 |
60 | .. code-block:: bash
61 |
62 | cd /usr/ports/varnish && make install clean
63 |
64 |
65 | Red Hat / CentOS
66 | ................
67 |
68 | The latest version is available as prebuilt RPMs (el5 and el6) on `https://packagecloud.io/varnishcache/`_ .
69 |
70 | See the online Red Hat installation instructions for more information.
71 |
72 | Varnish is included in the EPEL repository, however due to incompatible syntax
73 | changes in newer versions of Varnish, only older versions are available.
74 |
75 | We therefore recommend that you install the latest version directly from our
76 | repository, as described above.
77 |
78 | Debian/Ubuntu
79 | .............
80 |
81 | Varnish is distributed with both Debian and Ubuntu.
82 |
83 | Try
84 |
85 | .. code-block:: bash
86 |
87 | sudo apt-get install varnish
88 |
89 | Please note that this might not be the latest version of Varnish.
90 | If you need a newer version of Varnish for the OS version you are using,
91 | please follow the instructions in the Varnish Book or as shown below.
92 |
93 | - Start by grabbing the repository
94 |
95 | - Add the repository to the source list and save
96 |
97 | .. literalinclude:: /content/examples/varnish_install_repo
98 | :language: bash
99 |
100 | - Run update and install
101 |
102 | .. literalinclude:: /content/examples/update_install_varnish
103 | :language: bash
104 | For more information visit the `packagecloud`_ page.
105 |
106 | If you are installing Varnish Cache 4.0, replace varnish41 for varnish40 in
107 | the command above. Instructions for Debian and Ubuntu are the same.
108 |
109 |
110 | **Compiling Varnish from source**
111 | ---------------------------------
112 |
113 | If there are no binary packages available for your system,
114 | or if you want to compile Varnish from source for other reasons, such as personal
115 | interest or anything that counts as a reason, follow these steps:
116 |
117 | Download the appropriate release tarball, which you can find on the `repository source`_ .
118 |
119 | Alternatively, if you want to hack on Varnish, you should clone our git repository by doing:
120 |
121 | .. code-block:: bash
122 |
123 | git clone https://github.com/varnishcache/varnish-cache
124 |
125 | Requirements
126 | ............
127 |
128 | A UNIX machine or a Mac
129 |
130 | Build dependencies on Debian / Ubuntu
131 | ......................................
132 |
133 | In order to build Varnish from source you need a number of packages installed.
134 | On a Debian or Ubuntu system these are:
135 |
136 | .. code-block:: bash
137 |
138 | automake
139 | autotools-dev
140 | libedit-dev
141 | libjemalloc-dev
142 | libncurses-dev
143 | libpcre3-dev
144 | libtool
145 | pkg-config
146 | python-docutils
147 | python-sphinx
148 | graphviz
149 |
150 | Build dependencies on Red Hat / CentOS
151 | ......................................
152 |
153 | To build Varnish on a Red Hat or CentOS system you need the following packages installed:
154 |
155 | .. code-block:: bash
156 |
157 | autoconf
158 | automake
159 | jemalloc-devel
160 | libedit-devel
161 | libtool
162 | ncurses-devel
163 | pcre-devel
164 | pkgconfig
165 | python-docutils
166 | python-sphinx
167 | graphviz
168 |
169 |
170 | Build dependencies on a SmartOS Zone
171 | ....................................
172 |
173 | As of SmartOS pkgsrc 2015Q4, install the following packages:
174 |
175 | .. code-block:: bash
176 |
177 | pkgin in autoconf automake libedit libtool ncurses \
178 | pcre graphviz py27-sphinx python27 gmake gcc49 \
179 | pkg-config
180 |
181 | Optionally, to pull from a repository:
182 |
183 | .. code-block:: bash
184 |
185 | pkgin in git
186 |
187 |
188 | Building Varnish
189 | -----------------
190 |
191 | Finally if you have all of the above **dependencies satisfied**. You can move on to
192 | building your Varnish from *scratch*.
193 |
194 | .. code-block:: bash
195 |
196 | cd varnish-cache
197 | sh autogen.sh
198 | sh configure
199 | make
200 |
201 | The configure script takes some arguments, but more likely than not you can forget
202 | about that for now, almost everything in Varnish can be tweaked with runtime parameters.
203 |
204 | Before you install, you may want to run the test suite, and make a cup of tea while
205 | it runs, as it usually takes a couple of minutes:
206 |
207 | .. code-block:: bash
208 |
209 | make check
210 |
211 | *Don't worry if* one or two tests fail; some of the tests are a bit too timing
212 | sensitive. (Please tell us which so we can fix them.)
213 |
214 | **BUT**
215 |
216 | If a **lot of tests fail** and in particular if the **b00000.vtc test fails**,
217 | something is horribly wrong, and you will get nowhere without figuring out what is causing all the chaos.
218 |
219 | Good luck!
220 |
221 | Installing
222 | ..........
223 |
224 | And finally, the true test of a **brave heart!**
225 |
226 | .. code-block:: bash
227 |
228 | sudo make install
229 |
230 | - Varnish will now be installed in /usr/local.
231 | - The varnishd binary is in /usr/local/sbin/varnishd.
232 | - To make sure that the necessary links and caches of the most recent shared
233 | libraries are found, run
234 |
235 | .. code-block:: bash
236 |
237 | sudo ldconfig
238 |
239 | Using source: https://www.varnish-cache.org/docs/trunk/installation/install.html#compiling-varnish-from-source
240 |
241 | .. _`products at our website`: https://www.varnish-software.com/products/varnish-plus
242 | .. _`repository source`: https://varnish-cache.org/releases/
243 | .. _`packagecloud`: https://packagecloud.io/varnishcache
244 |
--------------------------------------------------------------------------------
/source/content/tutorials/varnish/multiple_varnishes.rst:
--------------------------------------------------------------------------------
1 |
2 | .. _multiple_varnishes:
3 |
4 | Dealing with multiple backends in Varnish
5 | =========================================
6 |
7 | If you are considering or already have more than one Varnish cache,
8 | you definitely have a huge network to **manage!**
9 |
10 | Having multiple backends
11 | ------------------------
12 |
13 | Multiple backends means serving from several servers.
14 | You want Varnish to map all the URLs into one single host. There are many options for doing this.
15 |
16 | Let's take a PHP application website to which you would like to add a Java application.
17 | Let's say your Java application should handle URLs beginning with /java/.
18 |
19 | Assuming that you already have a backend running at 8080 and serving content to
20 | users through port 80. This is your default VCL:
21 |
22 | .. code-block:: vcl
23 |
24 | backend default {
25 | .host = "127.0.0.1";
26 | .port = "8080";
27 | }
28 |
29 | Now let's add a new backend:
30 |
31 | .. code-block:: vcl
32 |
33 | backend java {
34 | .host = "127.0.0.1";
35 | .port = "8000";
36 | }
37 |
38 | Now we need to tell Varnish where to send the different URL. Here is what you
39 | need in your **vcl_recv** :
40 |
41 | .. literalinclude:: /content/examples/vcl_backend_hint.vcl
42 | :language: VCL
43 |
44 | As you can see you can define how to choose backends based on really arbitrary data.
45 | If you want to send mobile devices to a different backend, a little bit more
46 | VCL should do the trick.
47 |
48 | .. code-block:: vcl
49 |
50 | if (req.http.User-agent ~ /mobile/)
51 | ..
52 |
53 | If there is no backend defined, Varnish uses the default backend. If there is
54 | no backend named default, Varnish will use the first backend found in the VCL.
55 |
56 | Backends and virtual hosts in Varnish
57 | -------------------------------------
58 |
59 | Varnish fully supports virtual hosts!
60 |
61 | Virtual hosts might however work in a somewhat *counterintuitive fashion* since they are
62 | never declared explicitly. You have to set up the routing of incoming HTTP requests
63 | in `vcl_recv`. If you want this routing to be done on the basis of virtual hosts,
64 | you just need to inspect req.http.host.
65 |
66 | You can have something like this:
67 |
68 | .. literalinclude:: /content/examples/vcl_backend_virtualhosts.vcl
69 | :language: VCL
70 |
71 | Note that the first regular expressions will match "foo.com", "www.foo.com",
72 | "zoop.foo.com" and any other host ending in "foo.com".
73 |
74 | In this example this is intentional but you might want it to be a bit tighter,
75 | maybe relying on the **==** operator instead, like this:
76 |
77 | .. literalinclude:: /content/examples/vcl_backend_virtualhosts2.vcl
78 | :language: VCL
79 |
80 | Directors
81 | ---------
82 |
83 | You can also group several backends into a group of backends.
84 | These groups are called **directors**. This will give you increased performance
85 | and resilience.
86 |
87 | You can define several backends and group them together in a director.
88 | This requires you to load a VMOD, a Varnish module, and then to call certain
89 | actions in vcl_init.:
90 |
91 | .. literalinclude:: /content/examples/vcl_vmod_mbackend.vcl
92 | :language: VCL
93 |
94 |
95 | This director is a round-robin director. This means the director will distribute
96 | the incoming requests on a round-robin basis. There is also a random director
97 | that distributes requests in a, you guessed it, random fashion. If that is not
98 | enough, you can also write your own director (see Writing a Director).
99 |
100 | But what if one of your servers goes down? Can Varnish direct all the requests
101 | to the healthy server? Sure it can. This is where the health checks come into
102 | play.
103 |
104 | Health checks
105 | -------------
106 |
107 | Let's set up a director with two backends and health checks.
108 | First let us define the backends:
109 |
110 | .. literalinclude:: /content/examples/vcl_backend_healthcheck.vcl
111 | :language: VCL
112 |
113 | What is new here is the probe.
114 | In this example Varnish will check the health of each backend every 5 seconds,
115 | timing out after 1 second. Each poll will send a GET request to /.
116 | If 3 out of the last 5 polls succeeded the backend is considered healthy,
117 | otherwise it will be marked as sick.
118 |
119 | Refer to the Probes section in the VCL documentation for more information.
120 |
121 | Now we define the 'director':
122 |
123 | .. code-block:: vcl
124 |
125 | import directors;
126 |
127 | sub vcl_init {
128 | new vdir = directors.round_robin();
129 | vdir.add_backend(server1);
130 | vdir.add_backend(server2);
131 | }
132 |
133 | You use this vdir director as a backend_hint for requests, just like you would
134 | with a simple backend. Varnish will not send traffic to hosts that are marked as
135 | unhealthy.
136 |
137 | Varnish can also serve stale content if all the backends are down.
138 | See **Misbehaving servers** in the Varnish documentation for more information
139 | on how to enable this.
140 |
141 | Please note that Varnish will keep health probes running for all loaded VCLs.
142 | Varnish will coalesce probes that seem identical - so be careful not to change
143 | the probe config if you do a lot of VCL loading. Unloading the VCL will discard
144 | the probes.
145 |
146 | Source and more details `here`_ .
147 |
148 | .. _here: https://www.varnish-cache.org/docs/trunk/users-guide/vcl-backends.html?highlight=multiple%20varnish
149 |
--------------------------------------------------------------------------------
/source/content/tutorials/varnish/run_varnish.rst:
--------------------------------------------------------------------------------
1 | .. _run_varnish:
2 |
3 | Let's run Varnish!
4 | ==================
5 |
6 | Once you have installed Varnish, you can take advantage of a few tips to help you get started with
7 | running it.
8 |
9 | Integration
10 | -----------
11 |
12 | Where is your Varnish running?
13 |
14 | 1. Varnish is on the same machine as your web application.
15 | 2. Varnish is on a separate machine placed in front of the web server.
16 | 3. Varnish is on a separate machine placed in front of several web servers.
17 | 4. Varnish is on several machines integrated to work with multiple backend web servers.
18 |
19 | Configuring Varnish for 1 is quite simple and easy, but as you continue down that
20 | line, configuration and integration can become quite complex.
21 |
22 | Running Varnish for different applications is not just about placing Varnish in
23 | front of your web server and expecting it to do everything.
24 |
25 | Of course Varnish can do magical things without much configuration in Varnish.
26 | But only after you have integrated it correctly with your web servers.
27 |
28 | As you may already know, different web applications have different requirements.
29 |
30 | In order to help you with that, we provide guidelines for each type of
31 | web application, multiple backend setup, etc.
32 |
33 | Security
34 | --------
35 |
36 | Are you the only person running your Varnish?
37 |
38 | If you are the only one or all those who have access to Varnish are trusted to
39 | the same degree, you don't have to worry about security.
40 |
41 | Otherwise, if you have different administration levels, you might want to know
42 | about what services Varnish provides for that.
43 |
44 | Varnish provides four levels of security:
45 |
46 | - Command line arguments
47 | - CLI interface
48 | - VCL programs
49 | - HTTP requests
50 |
51 | Command line arguments
52 | ......................
53 |
54 | Starting/Stopping/Restarting/Reloading Varnish from command line requires
55 | administrator/sudo permissions.
56 |
57 | The important decisions to make are:
58 |
59 | - Who should have access to the command line Interface?
60 | - Which parameters can they change?
61 | - Will inline-C code be allowed?
62 | - If/how VMODs will be restricted?
63 | - How child processes will be jailed?
64 |
65 |
66 | CLI access
67 | ..........
68 |
69 | The command line interface can be accessed in three ways.
70 |
71 | varnishd can be told to listen and offer CLI connections on a TCP socket. You can
72 | bind the socket to pretty much anything the kernel will accept:
73 |
74 | .. code-block:: bash
75 |
76 | -T 127.0.0.1:631
77 | -T localhost:9999
78 | -T 192.168.1.1:34
79 | -T '[fe80::1]:8082'
80 |
81 | 1. The default is -T localhost:0 which will pick a random port number,
82 | which varnishadm(8) can learn from the shared memory.
83 |
84 | 2. You can bind the CLI port to a 'localhost' address, and give remote users
85 | access via a secure connection to the local machine, using ssh/VPN or similar.
86 |
87 | 3. It is also possible to configure varnishd for "reverse mode", using the '-M'
88 | argument. In that case varnishd will attempt to open a TCP connection to the
89 | specified address, and initiate a CLI connection to your central Varnish
90 | management facility.
91 |
92 | CLI interface authentication
93 | ............................
94 |
95 | By default the CLI interface is protected with a simple, yet powerful
96 | "pre-shared key" authentication method, which does not provide secrecy.
97 |
98 | To authenticate and use a CLI connection, you need to know the contents of this
99 | file, which was created during startup and contains random content and
100 | is only accessible to the user who started varnishd, in order to answer the
101 | cryptographic challenge varnishd issues. See Authentication with -S.
102 |
103 | If you want to allow other users, local or remote, to be able to access CLI
104 | connections, you must create your own secret file and make it possible for
105 | (only!) those users to read it.
106 |
107 | A good way to create the secret file is:
108 |
109 | .. code-block:: bash
110 |
111 | dd if=/dev/random of=/etc/varnish_secret count=1
112 |
113 |
114 | When starting varnishd or varnishadm use `-S` to provide the file name.
115 |
116 | Read more about `Authenticating -S`_
117 |
118 | Parameters
119 | ..........
120 | Parameters can be set from the command line, and made "read-only" (using '-r')
121 | so they cannot subsequently be modified from the CLI interface.
122 |
123 | Pretty much any parameter can be used to totally mess up your HTTP service,
124 | but a few listed below can do more damage than others:
125 |
126 | cc_command
127 | Execute arbitrary programs
128 |
129 | vcc_allow_inline_c
130 | Allow inline-C in VCL, which would make any C code from VCL be executed by Varnish.
131 |
132 | Furthermore you may want to look at and lock down:
133 |
134 | syslog_cli_traffic
135 | Log all CLI commands to syslog(8), so you know what's going on.
136 |
137 | vcc_unsafe_path
138 | Restrict VCL/VMODs to vcl_path and vmod_path
139 |
140 | vmod_path
141 | The directory (or colon separated list of directories) where Varnish will
142 | will look for modules. This could potentially be used to load rogue modules
143 | into Varnish.
144 |
145 | The CLI interface
146 | -----------------
147 |
148 | The CLI interface in Varnish is very powerful. If you have access to the CLI
149 | interface, you can do almost anything to the Varnish process.
150 |
151 | VCL programs
152 | ------------
153 |
154 | There are two "dangerous" mechanisms available in VCL code: VMODs and inline-C.
155 | Both of these mechanisms allow execution of arbitrary code and will thus allow a
156 | person to get access to the machine, with the privileges of the child process.
157 |
158 | HTTP requests
159 | -------------
160 |
161 | Since VCL is a programming language which lets you decide exactly what to do with
162 | HTTP requests, you can also decide to do stupid and potentially dangerous things
163 | with them, including opening yourself up to various kinds of attacks and
164 | subversive activities.
165 |
166 | If you have "administrative" HTTP requests, for instance PURGE requests, we
167 | strongly recommend that you restrict them to trusted IP numbers/nets using VCL's
168 | access control lists (ACLs).
169 |
170 | .. _`Authenticating -S`: https://www.varnish-cache.org/docs/trunk/users-guide/run_security.html
171 |
--------------------------------------------------------------------------------
/source/content/tutorials/varnish/sample_vclTemplate.rst:
--------------------------------------------------------------------------------
1 | .. _sample_vclTemplate:
2 |
3 | Sample VCLs
4 | ===========
5 |
6 | Based on the fantastic work of Mattias Geniar: https://github.com/mattiasgeniar/varnish-4.0-configuration-templates/
7 |
8 | Configuring Varnish
9 | -------------------
10 |
11 | ACL purge
12 | .........
13 |
14 | .. literalinclude:: /content/templates/vcl_defaultSample_mattias.vcl
15 | :language: VCL
16 | :lines: 32-37
17 |
18 | Backend definition
19 | ..................
20 |
21 | .. literalinclude:: /content/templates/vcl_defaultSample_mattias.vcl
22 | :language: VCL
23 | :lines: 7-30
24 |
25 | Normalizing header
26 | ..................
27 |
28 | .. literalinclude:: /content/templates/vcl_defaultSample_mattias.vcl
29 | :language: VCL
30 | :lines: 58,66-67,193
31 |
32 | Removing proxy header
33 | .....................
34 |
35 | .. literalinclude:: /content/templates/vcl_defaultSample_mattias.vcl
36 | :language: VCL
37 | :lines: 58,69-70,193
38 |
39 | Normalizing query arguments
40 | ...........................
41 |
42 | .. literalinclude:: /content/templates/vcl_defaultSample_mattias.vcl
43 | :language: VCL
44 | :lines: 58,72-73,193
45 |
46 | Allowing purging
47 | ................
48 |
49 | .. literalinclude:: /content/templates/vcl_defaultSample_mattias.vcl
50 | :language: VCL
51 | :lines: 58,75-83,193
52 |
53 | Dealing with selective header types
54 | ...................................
55 |
56 | .. literalinclude:: /content/templates/vcl_defaultSample_mattias.vcl
57 | :lines: 58,86-96,193
58 |
59 | Implementing web socket support example
60 | ........................................
61 |
62 | .. literalinclude:: /content/templates/vcl_defaultSample_mattias.vcl
63 | :lines: 58, 98-101,193,195, 212-217
64 |
65 | Sending traffic to vdir
66 | .......................
67 |
68 | When using external VMODs you need this.
69 |
70 | .. literalinclude:: /content/templates/vcl_defaultSample_mattias.vcl
71 | :lines: 58,64,193
72 |
73 | URL manipulation
74 | ----------------
75 |
76 | Making sure the POST requests are always passed
77 | ...............................................
78 |
79 | .. literalinclude:: /content/templates/vcl_defaultSample_mattias.vcl
80 | :lines: 58,103-106,193
81 |
82 | Removing Google Analytics added parameters
83 | ..........................................
84 |
85 | .. literalinclude:: /content/templates/vcl_defaultSample_mattias.vcl
86 | :lines: 58,110-115,193
87 |
88 | Example of stripping from URL
89 | .............................
90 |
91 | The example below strips ``#`` from URL, because server has no use for it.
92 |
93 | .. literalinclude:: /content/templates/vcl_defaultSample_mattias.vcl
94 | :lines: 58,117-120,193
95 |
96 | The example below strips trailing ``?`` from URL.
97 |
98 | .. literalinclude:: /content/templates/vcl_defaultSample_mattias.vcl
99 | :lines: 58,122-125,193
100 |
101 | Cookie manipulation
102 | -------------------
103 |
104 | Removing Google Analytics cookies
105 | .................................
106 |
107 | .. literalinclude:: /content/templates/vcl_defaultSample_mattias.vcl
108 | :lines: 58,131-137,193
109 |
110 | Removing doubleClick offensive cookies
111 | ......................................
112 |
113 | These cookies are used to improve advertising. Basically doubleClick ensures that
114 | users do not see the same advertisement twice. It sends a cookie when a user clicks
115 | on a ad. These cookies are not relevant for caching.
116 |
117 | .. literalinclude:: /content/templates/vcl_defaultSample_mattias.vcl
118 | :lines: 58,139-140,193
119 |
120 | Removing Quant Capital cookies
121 | ..............................
122 |
123 | .. literalinclude:: /content/templates/vcl_defaultSample_mattias.vcl
124 | :lines: 58,142-143,193
125 |
126 | Removing ADDThis cookies
127 | ........................
128 |
129 | .. literalinclude:: /content/templates/vcl_defaultSample_mattias.vcl
130 | :lines: 58,145-146,193
131 |
132 | Removing ';' prefix from cookies
133 | ................................
134 |
135 | .. literalinclude:: /content/templates/vcl_defaultSample_mattias.vcl
136 | :lines: 58,148-149,193
137 |
138 | Checking for empty or spaced cookies
139 | ....................................
140 |
141 | .. literalinclude:: /content/templates/vcl_defaultSample_mattias.vcl
142 | :lines: 58,151-165,193
143 |
144 |
145 | Turn on Varnish support for streaming
146 | .....................................
147 |
148 | .. literalinclude:: /content/templates/vcl_defaultSample_mattias.vcl
149 | :lines: 58,167-173,193
150 |
151 | Removing cookies for static files
152 | .................................
153 |
154 | .. literalinclude:: /content/templates/vcl_defaultSample_mattias.vcl
155 | :lines: 58,175-182,193
156 |
157 | ESI support
158 | -----------
159 |
160 | .. literalinclude:: /content/templates/vcl_defaultSample_mattias.vcl
161 | :lines: 58,184-190,193
162 |
163 | Hashing cookies
164 | ---------------
165 |
166 | .. literalinclude:: /content/templates/vcl_defaultSample_mattias.vcl
167 | :lines: 228,240-244
168 |
169 | Serving queued requests with Grace
170 | ..................................
171 |
172 | .. literalinclude:: /content/templates/vcl_defaultSample_mattias.vcl
173 | :lines: 246, 254-256, 264-287
174 |
175 | Passing real IP to backend
176 | --------------------------
177 |
178 | .. code-block:: VCL
179 |
180 | sub vcl_recv {
181 | if (req.restarts == 0) {
182 | if (req.http.X-Forwarded-For) {
183 | set req.http.X-Forwarded-For = req.http.X-Forwarded-For + ", " + client.ip;
184 | } else {
185 | set req.http.X-Forwarded-For = client.ip;
186 | }
187 | }
188 | }
189 |
190 |
191 | Handling request from backend
192 | -----------------------------
193 |
194 | How Varnish handles the HTTP request coming from our backends relies on the VCL
195 | we write in our backend subroutines.
196 |
197 | The vcl_backend_response subroutine is called after the response headers are
198 | successfully retrieved from the backend.
199 |
200 | Pausing ESI request
201 | ...................
202 |
203 | .. literalinclude:: /content/templates/vcl_defaultSample_mattias.vcl
204 | :lines: 298,301-305,348-349
205 |
206 |
207 | Enabling cache for static files
208 | ...............................
209 |
210 | .. literalinclude:: /content/templates/vcl_defaultSample_mattias.vcl
211 | :lines: 298,310-312,348-349
212 |
213 | Streaming
214 | .........
215 |
216 | .. literalinclude:: /content/templates/vcl_defaultSample_mattias.vcl
217 | :lines: 298,316-320,348-349
218 |
219 | Redirecting
220 | ...........
221 |
222 | Sometimes, a 301 or 302 redirect formed via Apache's mod_rewrite can mess with the HTTP port that is being passed along.
223 | This often happens with simple rewrite rules in a scenario where Varnish runs on :80 and Apache on :8080 on the same box.
224 | A redirect can then often redirect the end-user to a URL on :8080, where it should be :80.
225 | This may need fine-tuning on your setup.
226 |
227 | .. literalinclude:: /content/templates/vcl_defaultSample_mattias.vcl
228 | :lines: 298,327-330,348-349
229 |
230 | Setting cache for static files if unset
231 | .......................................
232 |
233 | .. literalinclude:: /content/templates/vcl_defaultSample_mattias.vcl
234 | :lines: 298,332-337,348-349
235 |
236 | Example of excluding from cache
237 | ...............................
238 |
239 | .. literalinclude:: /content/templates/vcl_defaultSample_mattias.vcl
240 | :lines: 298,339-342,348-349
241 |
242 | Setting Grace mode
243 | ..................
244 |
245 | .. literalinclude:: /content/templates/vcl_defaultSample_mattias.vcl
246 | :lines: 298,344-346,349
247 |
248 |
249 | Adding debug headers
250 | ....................
251 |
252 | .. literalinclude:: /content/templates/vcl_defaultSample_mattias.vcl
253 | :lines: 353,356-360,378-379
254 |
255 | Handling HTTP purge
256 | ...................
257 |
258 | .. literalinclude:: /content/templates/vcl_defaultSample_mattias.vcl
259 | :lines: 381-388
260 |
261 |
262 | vcl_synth
263 | .........
264 |
265 | .. literalinclude:: /content/templates/vcl_defaultSample_mattias.vcl
266 | :lines: 390-406
267 |
--------------------------------------------------------------------------------
/source/content/tutorials/varnish/troubleshooting_varnish.rst:
--------------------------------------------------------------------------------
1 | .. _troubleshooting_varnish:
2 |
3 |
4 | Troubleshooting Varnish
5 | =======================
6 |
7 | **Have you tried turning your Varnish off and on again?**
8 |
9 | Reload Varnish
10 | ..............
11 |
12 | .. code-block:: bash
13 |
14 | sudo systemctl reload varnish.service
15 |
16 |
17 | Stop and start Varnish
18 | ......................
19 |
20 | .. code-block:: bash
21 |
22 | sudo systemctl start varnish.service
23 | sudo systemctl stop varnish.service
24 |
25 | Restart Varnish
26 | ...............
27 |
28 | .. code-block:: bash
29 |
30 | sudo systemctl restart varnish.service
31 |
32 |
33 | **Still NOT working???**
34 |
35 | Try to start Varnish in debug mode!
36 | -----------------------------------
37 |
38 | For systemv users:
39 |
40 | .. literalinclude:: /content/examples/vclex_startvarnish_debugmode.vcl
41 | :language: VCL
42 |
43 | For systemd users:
44 |
45 | .. literalinclude:: /content/examples/vclex_startvarnish_debugmode.vcl
46 | :language: VCL
47 |
48 | Varnish is crashing?
49 | --------------------
50 |
51 | If your Varnish is crashing it might be due to a number of reasons.
52 | Here are a few things you can try.
53 |
54 | panics
55 | ......
56 |
57 | You can inspect any panic messages by typing the following in the CLI:
58 |
59 | .. code-block:: python
60 |
61 | panic.show
62 |
63 |
64 | segfaults
65 | .........
66 |
67 | This is a Varnish segmentation error. When this happens with the child process
68 | it is logged, the core is dumped and the child process starts up again.
69 |
70 | If you need help solving your segfaults issue and can log onto our IRC channel
71 | #varnish and get help or if have a subscription, please call us and we will help
72 | you fix it.
73 |
74 |
75 | Varnish gives me Guru Meditation
76 | --------------------------------
77 |
78 | This means that your backends might be experiencing some kind of issue. To solve
79 | an issue like this, checkout varnishhlog.
80 |
81 | You can set varnishlog to log all your 503 errors by issuing the following command:
82 |
83 | .. code-block:: bash
84 |
85 | $ varnishlog -q 'RespStatus == 503' -g request
86 |
87 | If the error happened just a short time ago the transaction might still be in
88 | the shared memory log segment. To get varnishlog to process the whole shared
89 | memory log just add the '-d' parameter:
90 |
91 | .. code-block:: bash
92 |
93 | $ varnishlog -d -q 'RespStatus == 503' -g request
94 |
95 |
96 | Varnish is not caching
97 | ----------------------
98 |
99 | If your Varnish is not caching you can follow our simple steps to receive high hit rate or
100 | follow the detailed `User Guide`_
101 |
102 |
103 | For details on troubleshooting Varnish, look at the user guide
104 | `Troubleshooting Varnish Section`_
105 |
106 | .. _`User Guide`: https://www.varnish-cache.org/docs/4.1/users-guide/increasing-your-hitrate.html#users-guide-increasing-your-hitrate
107 | .. _`Troubleshooting Varnish Section`: https://www.varnish-cache.org/docs/4.1/users-guide/troubleshooting.html#users-trouble
108 |
--------------------------------------------------------------------------------
/source/content/tutorials/varnish/varnishCacheVersions.rst:
--------------------------------------------------------------------------------
1 |
2 | .. _varnish_versions:
3 |
4 | Which version of Varnish to use?
5 | ================================
6 |
7 | We recommend that you always choose to use the latest stable release.
8 |
9 | **Varnish 3** - *end of life*
10 |
11 | If you are still using **varnish 3**, it's time to let it go and move on to **varnish 4** and upwards.
12 |
13 | The *most viral change* from **varnish 3 to 4** is how the complete thread model has changed;
14 | In Varnish 3 - one thread served each client whether from the backend or the cache.
15 | In Varnish 4 - there are two separate threads: one for client, one for backend.
16 | This allows varnish to serve stale content to the client while refreshing
17 | content in the background.
18 |
19 | `What is new in Varnish 4?`_
20 |
21 | .. _`What is new in Varnish 4?`: http://book.varnish-software.com/4.0/chapters/Introduction.html#what-is-new-in-varnish-4
22 |
23 | `Upgrading to Varnish 4`_
24 |
25 | .. _`Upgrading to Varnish 4`: https://www.varnish-cache.org/docs/trunk/whats-new/upgrading.html
26 |
27 | **Migrating to Varnish 4?**
28 |
29 | We advise that you should use the **VCL Migrator** at your risk.
30 |
31 | VCL Migrator
32 | ............
33 |
34 | The **VCL Migrator** is a script named varnish3to4, which will help you migrate
35 | from Varnish 3 to 4. There have been numerous syntactical changes in the
36 | VCL codes from Varnish 3 to 4. It is not quite intensive, but using the script
37 | to migrate can help save you time and will also make the new changes visible for you.
38 | This aim is to make your future VCL configuration work easier.
39 |
40 | You can download the `varnish3to4 script here`_
41 |
42 | .. _`varnish3to4 script here`: https://github.com/fgsch/varnish3to4
43 |
44 | All details and updates are included in the link. You assume full responsibility for your use.
45 |
--------------------------------------------------------------------------------
/source/content/tutorials/varnish/varnish_test.rst:
--------------------------------------------------------------------------------
1 | .. _varnish_test:
2 |
3 | Testing with varnishtest
4 | ========================
5 |
6 | You may not be aware of this, but `VarnishTest` is an awesome tool.
7 | varnishtest is a sandbox (testing environment) that is completely isolated from
8 | the production environment where one can TEST untested code changes and do
9 | all kinds of out-of-this-world experimentation.
10 |
11 | varnishtest protects your "live" servers, reviewed VCL codes and
12 | other collections of data and/or content from severe changes that could be caused
13 | by experimental code. We all know that once in a mission-critical system
14 | phase it is quite difficult to revert back.
15 |
16 | Varnish comes with varnishtest pre-installed and runs personalized tests for
17 | whatever case you define. There is also a whole set of pre-defined tests
18 | that you can use to help your understanding and testing.
19 |
20 | Here is a list of contexts where you can use `VarnishTest`:
21 |
22 | - Testing your Varnish and backend installation
23 | - Configuring your Varnish Cache installation
24 | - When writing complex caching policies in VCL such as:
25 | - test a cache invalidation method
26 | - reproduce bugs when filing a report
27 | - When tuning Varnish Cache
28 | - To define and test modules for Varnish Cache extensions (VMOD)
29 | - Writing applications that integrate well with Varnish Cache and utilize all its characteristics.
30 |
31 | The Varnish Testcase Language (VTC)
32 | ------------------------------------
33 |
34 | This is the language that varnishtest understands. The extension used by Varnish
35 | test case files is (.vtc).
36 |
37 | Normally, a VTC file describes a scenario with different scripted HTTP-talking
38 | operations and generally one or more Varnish instances (clients) to test.
39 |
40 | Naming convention
41 | .................
42 |
43 | varnishtest has a whole set of pre-defined tests that you can use if you understand what it is doing. It follows a naming convention, which will help you to understand which set is what type of example.
44 |
45 | .. literalinclude:: /content/examples/vtc/vtc_syntax.txt
46 |
47 | **Note:** You can use any naming convention to write your test, but a defined
48 | naming convention could help you to avoid rewriting similar tests.
49 |
50 | Name the test
51 | .............
52 |
53 | varnishtest requires that you name the test.
54 | Here is an example:
55 |
56 | .. code-block:: VCL
57 |
58 | varnishtest "This is a varnishtest for testing"
59 |
60 |
61 | Defining the components
62 | -----------------------
63 |
64 | varnishtest requires three components to run the test:
65 |
66 | - A server (origin server)
67 | - A Varnish Cache instance
68 | - A client
69 |
70 | .. image:: /image/varnishtest_anatomy.svg
71 | :alt: Sphinx Neo-Hittite
72 | :align: center
73 | :scale: 100%
74 |
75 | Declaring the server
76 | ....................
77 |
78 | - A server declaration must start with **s**
79 | - `rxreq` : accepts/receives requests
80 | - `txresp` : transmits/responds to requests
81 | - `- start` : boots server
82 |
83 | What follows is an example of declaring a server:
84 |
85 | .. literalinclude:: /content/examples/vtc/example.vtc
86 | :language: VCL
87 | :lines: 4-7
88 |
89 |
90 | Declaring the Varnish Cache instance
91 | ....................................
92 |
93 | - A Varnish Cache instance declaration must start with **v**
94 | - Instance controlled by the manager process
95 | - `- start` : forks a child for this instance from the actual cache process
96 |
97 |
98 | What follows is an example of declaring a Varnish Cache instance:
99 |
100 | .. literalinclude:: /content/examples/vtc/example.vtc
101 | :language: VCL
102 | :lines: 9
103 |
104 | Declaring a client
105 | ..................
106 |
107 | - Stimulated client declaration must start with **c**
108 | - `- run` : starts the client
109 |
110 | What follows is an example of declaring a Varnish Cache instance:
111 |
112 | .. literalinclude:: /content/examples/vtc/example.vtc
113 | :language: VCL
114 | :lines: 11-16
115 |
116 | In this example, c1 transmits one request and receives one response.
117 |
118 | Since Varnish is a proxy instance, the response should be received from the backend
119 | via Varnish Cache (Varnish instance in this case).
120 |
121 | - we can see c1 expects Varnish in the via HTTP header field.
122 | - The tilde (~) is used as a match operator of regular expressions
123 | - the exact name of the variable here (e.g. resp.http.via) depends on the version
124 | of Varnish installed.
125 |
126 | Running the test
127 | ----------------
128 |
129 | - To run the test, issue the command as shown below:
130 |
131 | .. code-block:: bash
132 |
133 | varnishtest example.vtc
134 |
135 | **Note:** If you are writing your own test, make sure that you point to the
136 | directory where the test is stored.
137 |
138 | This is the positive output to expect:
139 |
140 | .. code-block:: VCL
141 |
142 | # top TEST example.vtc passed (1.709)
143 |
144 | If you feel the need to inspect/understand the test better, you can always try the
145 | verbose mode with a `-v` as shown below:
146 |
147 | .. code-block:: VCL
148 |
149 | varnishtest -v example.vtc
150 |
151 | This is what a verbose output looks like for the ``example.vtc``:
152 |
153 | .. literalinclude:: /content/examples/vtc/example_voutput.vtc
154 | :language: bash
155 |
156 | Taking your varnishtest to the next level
157 | ------------------------------------------
158 |
159 | Connecting a real backend
160 | -------------------------
161 |
162 | .. literalinclude:: /content/examples/vtc/vtc_addRunningBackend.vtc
163 | :language: VCL
164 |
165 | Server - Answering more than one request
166 | .........................................
167 |
168 | .. literalinclude:: /content/examples/vtc/vtc_ServerReq.vtc
169 | :language: VCL
170 | :lines: 1-9
171 |
172 | Server - Expecting a request with URL
173 | ......................................
174 |
175 | .. literalinclude:: /content/examples/vtc/vtc_ServerReq.vtc
176 | :language: VCL
177 | :lines: 11-17
178 |
179 |
180 | Server - Expecting particular text in body
181 | ...........................................
182 |
183 | .. literalinclude:: /content/examples/vtc/vtc_ServerReq.vtc
184 | :language: VCL
185 | :lines: 19-31
186 |
187 | Client - Expecting response
188 | ...........................
189 |
190 | .. literalinclude:: /content/examples/vtc/vtc_ClientReq.vtc
191 | :language: VCL
192 |
193 | Setting Varnish to expect
194 | .........................
195 |
196 | .. literalinclude:: /content/examples/vtc/vtc_varnishExpect.vtc
197 | :language: VCL
198 |
199 |
200 | You may have noticed varnishtest preparing, executing
201 |
202 | Some resources to look at for `VarnishTest`_
203 | ---------------------------------------------
204 |
205 | If you want to try out the test cases available with varnishtest,
206 | `clone`_ the `varnish-cache repository from github`_ and visit the folder:
207 |
208 | .. code-block:: bash
209 |
210 | cd varnish-cache/bin/varnishtest/tests
211 |
212 | All the tests are here. Run them with ``VarnishTest``
213 |
214 |
215 | `Naming Scheme for VarnishTest`_
216 |
217 | Another great post at `Smashing Magazine about VarnishTest`_ written by our
218 | field engineer, Arianna Aondio
219 |
220 | `Understanding VTC`_
221 |
222 | `VarnishTest for Humans`_
223 |
224 | `Getting started with VarnishTest`_
225 |
226 | .. _`Getting started with VarnishTest`: https://open.blogs.nytimes.com/2016/08/29/testing-varnish-using-varnishtest/
227 | .. _`Clone`: https://github.com/varnishcache/varnish-cache.git
228 | .. _`varnish-cache repository from github`: https://github.com/varnishcache/varnish-cache
229 | .. _`VarnishTest for Humans`: https://github.com/xcir/vtctrans
230 | .. _`VarnishTest`: https://www.varnish-cache.org/docs/trunk/reference/varnishtest.html
231 | .. _`Understanding VTC`: https://www.varnish-cache.org/docs/trunk/reference/vtc.html?highlight=varnishtest
232 | .. _`Naming Scheme for VarnishTest`: https://raw.githubusercontent.com/varnish/Varnish-Cache/master/bin/varnishtest/tests/README
233 | .. _`Smashing Magazine about VarnishTest`: https://www.smashingmagazine.com/2016/05/five-simple-steps-test-varnish-cache-deployment-varnishtest/
234 |
--------------------------------------------------------------------------------
/source/content/tutorials/varnish/vcl.rst:
--------------------------------------------------------------------------------
1 | .. _vcl:
2 |
3 | Varnish Configuration Language (VCL)
4 | ====================================
5 |
6 | One of the key features of Varnish Cache, in addition to its performance, is the
7 | flexibility of its own configuration language, Varnish Configuration Language
8 | (VCL).
9 |
10 |
11 | Is VCL worth the learning curve?
12 | --------------------------------
13 |
14 | Looking for motivation? Well VCL is easy and very much like C. In fact, VCL accepts
15 | inline C, though it is not recommended. Following our guide and learning VCL is the
16 | way to go!
17 |
18 | We consider getting past your fear of coding and learning VCL a good choice
19 | because writing or modifying VCL can help you understand Varnish better. In fact,
20 | it will give you the independence to do whatever you want with your Varnish – at
21 | your own risk, of course! As you already know, many high-profile websites use Varnish,
22 | and if you are prepared to take your VCL skills to the next level, you will be taking a big step
23 | in doing big things with Varnish.
24 |
25 | How to VCL
26 | -----------
27 |
28 | The basics
29 | ..........
30 |
31 | - Domain-specific language
32 | - VCL as a finite state machine
33 | - States are sub-routines, e.g. `sub vcl_recv`
34 | - Varnish includes built-in subroutines, starting with `vcl_` (reserved prefix)
35 | - Varnish has a built-in VCL that is always appended with your custom VCL
36 | UNLESS you specify otherwise with a `return (hash)`. This terminates the subroutine,
37 | and DOES NOT append built-in VCL.
38 | - Available features: `functions, legal return actions and variables`_
39 |
40 |
41 | What is built-in VCL?
42 | ---------------------
43 |
44 | The built-in VCL file named `builtin.vcl` is the VCL configuration Varnish
45 | automatically appends to your VCL file during compilation/loading.
46 |
47 | Whenever a new configuration is loaded, the varnishd management process
48 | translates the VCL code to C and compiles it to a shared object, which is then
49 | loaded into the server process.
50 |
51 | You can view your `built-in vcl` in this location if you are a debian user:
52 |
53 | .. code-block:: bash
54 |
55 | cat /usr/share/doc/varnish/builtin.vcl
56 |
57 |
58 | **Note:** This ``builtin.vcl`` file is just for Varnish users to see what is
59 | present in the built-in file. Editing this VCL doesn't affect anything.
60 | Any VCL you want to add goes into /etc/varnish/default.vcl
61 |
62 | If you want to recreate your own VCL, we recommend you make changes in the
63 | `example.vcl`. You will find that file in this location if you are a debian user:
64 |
65 | .. code-block:: bash
66 |
67 | cat /usr/share/doc/varnish/example.vcl
68 |
69 |
70 | Built-in subroutines
71 | --------------------
72 |
73 | VCL built-in subroutines are the ones that are pre-defined using the syntax
74 | `vcl_` in the `builtin.vcl` and `default.vcl` (the subroutines here are empty
75 | by default).
76 |
77 |
78 | Here is a simplified version of how the VCL works frontend to backend.
79 | Click on the image to see a larger, clearer version.
80 |
81 | .. image:: /image/simplified_fsm.svg
82 | :alt: Sphinx Neo-Hittite
83 | :align: center
84 | :width: 400px
85 |
86 | (Taken from the Varnish book)
87 |
88 |
89 | Client side
90 | ...........
91 |
92 | **vcl_recv:**
93 |
94 | - called at the beginning of a request
95 | - after complete request has been received and parsed
96 | - after a restart
97 | - terminates with `return(action)`
98 | - action types:
99 | - hash (passes to vcl_hash)
100 | - pass (passes to vcl_pass)
101 | - pipe (passes to vcl_pipe)
102 | - synth (status code, reason):
103 | synth transition to vcl_synth with resp.status and resp.reason being preset
104 | to the arguments of synth()
105 | - purge (control passes through vcl_hash to vcl_purge)
106 |
107 | **vcl_pipe:**
108 |
109 | - called when entering pipe mode
110 | - this mode passes request to backend
111 | - terminates with `return(action)`
112 | - action types:
113 | - pipe
114 | - synth (status code, reason)
115 |
116 | **vcl_pass:**
117 |
118 | - called upon entering pass mode
119 | - the request is passed on to the backend
120 | - the backend's response is passed on to the client
121 | - but not entered into the cache
122 | - subsequent requests submitted over the same client connection are
123 | handled normally
124 | - terminates with `return(action)`
125 | - action types:
126 | - fetch (proceed with pass mode - initiate a backend request)
127 | - restart
128 | - synth (status code, reason)
129 |
130 | **vcl_hit:**
131 |
132 | - called when a cache lookup is successful
133 | - object being hit may be stale if:
134 | - it can have a zero, or
135 | - negative TTL with only grace, or
136 | - keep time left
137 | - terminates with `return(action)`
138 | - action types:
139 | - deliver (delivers the object, if stale then background fetch triggered)
140 | - miss (refresh the object and pass to vcl_miss)
141 | - restart
142 | - synth (status code, reason)
143 |
144 | **vcl_miss:**
145 |
146 | - called after a cache lookup **if** the requested document was not found in cache
147 | - it decides whether or not to attempt to retrieve the document from the backend
148 | - terminates with `return(action)`
149 | - action type:
150 | - fetch
151 | - pass
152 | - restart
153 | - synth (status code, reason)
154 |
155 | **vcl_hash:**
156 |
157 | - called after vcl_recv to create a hash value for the request
158 | - this key is used further to look up the object in cache
159 | - terminates only with return(lookup):
160 | - lookup (looks up the object in cache, passes to whichever subroutine called it)
161 |
162 | **vcl_purge:**
163 |
164 | - called after the purge has been executed and all its variants have been exited
165 | - terminates with `return(action)`
166 | - action type:
167 | - restart
168 | - synth (status code, reason)
169 |
170 | **vcl_synth:**
171 |
172 | - called to deliver a synthetic object
173 | - never enters cache
174 | - a synthetic object is generated in VCL (NOT fetched from backend)
175 | - the object's body is constructed using the `synthetic()` function
176 | - terminates with `return(action)`
177 | - action type:
178 | - restart
179 | - deliver (delivers to client without calling vcl_deliver)
180 |
181 | **vcl_deliver:**
182 |
183 | - called before any object is delivered to client (except vcl_synth)
184 | - terminates with `return(action)`
185 | - action type:
186 | - restart
187 | - deliver
188 | - synth(status code, reason)
189 |
190 |
191 | Backend side
192 | ............
193 |
194 | **vcl_backend_fetch:**
195 |
196 | - called before sending the backend request
197 | - usually the request is altered here before it gets to the backend
198 | - terminates with return(action)
199 | - fetch
200 | - abandon (abandons request UNLESS the request was a background fetch,
201 | then it is passed to vcl_synth)
202 |
203 | **vcl_backened_response:**
204 |
205 | - called after the response headers have been successfully retrieved from backend
206 | - terminates with return(action)
207 | - deliver
208 | - abandon
209 | - retry (increases re-try counter)
210 |
211 | **vcl_backened_error:**
212 |
213 | - called if backend fetch has failed or if `max_retries` has been exceeded
214 | - synthetic object is generated in VCL using the `synthetic()` function
215 | - may end up in cache
216 | - terminates with return(action)
217 | - deliver
218 | - retry
219 |
220 | vcl.load/vcl.discard
221 | ....................
222 |
223 | **vcl_init:**
224 |
225 | - called when VCL is loaded
226 | - before any request passes
227 | - typically called used to initialize VMODs
228 | - terminates with return(action)
229 | - ok
230 | - fail
231 |
232 | **vcl_fini:**
233 |
234 | - called when VCL is discarded, ONLY after ALL requests have exited VCL
235 | - used to clean up VMODs
236 | - terminates with return(action)
237 | - ok (normal return, VCL will be discarded)
238 |
239 | More details `subroutines here`_
240 |
241 | .. _`subroutines here`: https://www.varnish-cache.org/docs/trunk/users-guide/vcl-built-in-subs.html
242 | .. _`functions, legal return actions and variables`: https://www.varnish-cache.org/docs/6.0/reference/vcl.html
243 |
--------------------------------------------------------------------------------
/source/content/tutorials/varnish/vcl_examples.rst:
--------------------------------------------------------------------------------
1 | .. _vcl_examples:
2 |
3 | Cache invalidation with examples
4 | ================================
5 |
6 | Here we will explain with examples how the different components of cache
7 | invalidation work.
8 |
9 | HTTP purge
10 | ----------
11 |
12 | .. literalinclude:: /content/examples/vcl_purgeFromBackend.vcl
13 | :language: VCL
14 |
15 |
16 | PURGE an article from the backend
17 | .................................
18 |
19 | .. literalinclude:: /content/examples/vcl_purgeFromBackend.vcl
20 | :language: VCL
21 |
22 | Purge with restart
23 | ..................
24 |
25 | This allows Varnish to re-run the VCL state machine with different variables.
26 |
27 | .. literalinclude:: /content/examples/vcl_purgeWithRestart.vcl
28 | :language: VCL
29 |
30 | Source: http://book.varnish-software.com/4.0/chapters/Cache_Invalidation.html?highlight=vcl_recv
31 |
32 | Accessed: 17th August 2016
33 |
34 | Softpurge
35 | ---------
36 |
37 | - Reduces TTL to 0
38 | - Allows Varnish to serve stale objects
39 |
40 |
41 | .. literalinclude:: /content/examples/vclex_softPurge.vcl
42 | :language: VCL
43 |
44 | source: https://github.com/varnish/varnish-modules/blob/master/docs/vmod_softpurge.rst
45 |
46 | Accessed: 17th August 2016
47 |
48 | Purge call
49 | ...........
50 |
51 |
52 |
53 | Purge call to X-Headers
54 | .......................
55 |
56 |
57 | Banning
58 | -------
59 |
60 | Examples in the varnishadm command line interface:
61 |
62 | .. code-block:: VCL
63 |
64 | ban req.url ~ /foo
65 | ban req.http.host ~ example.com && obj.http.content-type ~ text
66 | ban.list
67 |
68 | Example in VCL:
69 |
70 | .. code-block:: VCL
71 |
72 | ban("req.url ~ /foo");
73 |
74 | Example of VCL code to act on HTTP BAN request method:
75 |
76 | .. code-block:: VCL
77 |
78 | sub vcl_recv {
79 | if (req.method == "BAN") {
80 | ban("req.http.host == " + req.http.host +
81 | " && req.url == " + req.url);
82 | # Throw a synthetic page so the request won't go to the backend.
83 | return(synth(200, "Ban added"));
84 | }
85 | }
86 |
87 | source: http://book.varnish-software.com/4.0/chapters/Cache_Invalidation.html
88 |
89 | To inspect the current ban-list, issue the ban.list command in the CLI:
90 |
91 | .. code-block:: VCL
92 |
93 | 0xb75096d0 1318329475.377475 10 obj.http.x-url ~ test0
94 | 0xb7509610 1318329470.785875 20C obj.http.x-url ~ test1
95 |
96 | Lurker-friendly bans
97 | ....................
98 |
99 | The following snippet shows an example of how to preserve the context of a client request in the cached object:
100 |
101 | .. code-block:: VCL
102 |
103 | sub vcl_backend_response {
104 | set beresp.http.x-url = bereq.url;
105 | }
106 |
107 | sub vcl_deliver {
108 | # The X-Url header is for internal use only
109 | unset resp.http.x-url;
110 | }
111 |
112 | Now imagine that you just changed a blog post template that requires all blog
113 | posts that have been cached. For this you can issue a ban such as:
114 |
115 | .. code-block:: VCL
116 |
117 | $ varnishadm ban 'obj.http.x-url ~ ^/blog'
118 |
119 | Since it uses a lurker-friendly ban expression, the ban inserted in the ban list
120 | will be gradually evaluated against all cached objects until all blog posts are
121 | invalidated. The snippet below shows how to insert the same expression into the
122 | ban list in the vcl_recv subroutine:
123 |
124 | .. code-block:: VCL
125 |
126 | sub vcl_recv {
127 | if (req.method == "BAN") {
128 |
129 | # Assumes the ``X-Ban`` header is a regex,
130 | # this might be a bit too simple.
131 |
132 | ban("obj.http.x-url ~ " + req.http.x-ban);
133 | return(synth(200, "Ban added"));
134 | }
135 | }
136 |
137 |
138 | Purge and ban together example
139 | ..............................
140 |
141 | .. code-block:: VCL
142 |
143 | sub vcl_recv {
144 | if (req.method == "PURGE") {
145 | return (purge);
146 | }
147 |
148 | if (req.method == "BAN") {
149 | ban("obj.http.x-url ~ " + req.http.x-ban-url +
150 | " && obj.http.x-host ~ " + req.http.x-ban-host);
151 | return (synth(200, "Ban added"));
152 | }
153 |
154 | if (req.method == "REFRESH") {
155 | set req.method = "GET";
156 | set req.hash_always_miss = true;
157 | }
158 | }
159 |
160 | sub vcl_backend_response {
161 | set beresp.http.x-url = bereq.url;
162 | set beresp.http.x-host = bereq.http.host;
163 | }
164 |
165 | sub vcl_deliver {
166 | # We remove resp.http.x-* HTTP header fields,
167 | # because the client does not neeed them
168 | unset resp.http.x-url;
169 | unset resp.http.x-host;
170 | }
171 |
172 |
173 |
174 | Force cache miss
175 | ----------------
176 |
177 | .. code-block:: VCL
178 |
179 | sub vc_recv {
180 | set req.hash_always_miss = true;
181 | }
182 |
183 | Causes Varnish to look the object up in cache, but ignore any copy it finds
184 | This is a useful way to do a controlled refresh of a specific object.
185 | If the server is down, the cached object is left untouched.
186 | Depending on the Varnish version, it might leave extra copies in the cache.
187 | It is useful to refresh slowly generated content.
188 |
189 | source: http://book.varnish-software.com/4.0/chapters/Appendix_G__Solutions.html#solution-write-a-vcl-program-using-purge-and-ban
190 |
191 | Xkey (formerly known as Hashtwo)
192 | --------------------------------
193 |
194 | The idea behind Xkey is that you can use any arbitrary string for cache invalidation.
195 | You can then key your cached objects on, for example, product ID or article ID.
196 | In this way, when you update the price of a certain product or a specific article,
197 | you have a key to evict all those objects from the cache.
198 |
199 | Xkey can be used to support Surrogate Keys in Varnish in a very flexible way.
200 |
201 | On Debian or Ubuntu:
202 |
203 | .. code-block:: bash
204 |
205 | apt-get install varnish-modules
206 |
207 | On Red Hat Enterprise Linux:
208 |
209 | .. code-block:: bash
210 |
211 | yum install varnish-modules
212 |
213 | Finally, you can use this VMOD by importing it into your VCL code:
214 |
215 | .. code-block:: VCL
216 |
217 | import xkey;
218 |
219 | VCL example code for xkey:
220 |
221 | .. code-block:: VCL
222 |
223 | import xkey;
224 |
225 | backend default { .host = "192.0.2.11"; .port = "8080"; }
226 |
227 | acl purgers {
228 | "203.0.113.0"/24;
229 | }
230 |
231 | sub vcl_recv {
232 | if (req.method == "PURGE") {
233 | if (client.ip !~ purgers) {
234 | return (synth(403, "Forbidden"));
235 | }
236 | set req.http.n-gone = xkey.purge(req.http.key);
237 | # or: set req.http.n-gone = xkey.softpurge(req.http.key)
238 |
239 | return (synth(200, "Invalidated "+req.http.n-gone+" objects"));
240 | }
241 | }
242 |
243 | Normally the backend is responsible for setting these headers.
244 | If you were to do it in VCL, it would look something like this:
245 |
246 | .. code-block:: VCL
247 |
248 | sub vcl_backend_response {
249 | set beresp.http.xkey = "secondary_hash_key";
250 | }
251 |
252 | source: http://book.varnish-software.com/4.0/chapters/Cache_Invalidation.html
253 | A complete Grace example
254 | ------------------------
255 |
256 | .. literalinclude:: /content/examples/grace-v4.vcl
257 | :language: VCL
258 |
259 | Source: https://info.varnish-software.com/blog/grace-varnish-4-stale-while-revalidate-semantics-varnish
260 |
261 | Accessed: 17th August 2016
262 |
263 | **ref to examples in vcl**
264 |
265 | IDEA: https://info.varnish-software.com/blog/10-varnish-cache-mistakes-and-how-avoid-them
266 |
--------------------------------------------------------------------------------
/source/content/tutorials/wordpress/index.rst:
--------------------------------------------------------------------------------
1 | .. _wordpress:
2 |
3 | WordPress with Varnish
4 | ======================
5 |
6 | .. toctree::
7 | :hidden:
8 |
9 | wp_step_by_step
10 | wp_vcl
11 |
12 |
13 | WordPress is a one of the most well-known open source content management systems
14 | (CMS) existing today. If you have a WordPress site and want to implement a caching solution,
15 | Varnish may be right for you. Depending on the amount of traffic and the complexity of your WordPress
16 | theme, performance maybe lagging. Varnish Cache is your recommended solution.
17 |
18 | Moreover you are not the first to want to do this. There are millions of WordPress
19 | websites using Varnish and some of the popular cache plugins written by other
20 | Varnish-WordPress users.
21 |
22 | Implementing WordPress with Varnish
23 | -----------------------------------
24 |
25 | Varnish is easy to set up and use. Since we have an open source project you are
26 | always welcome to try our community edition and contribute your fair share
27 | of new libraries, plugins and features.
28 |
29 | So where in WordPress will you be integrating Varnish?
30 |
31 | Installation
32 | ------------
33 |
34 | If you are ready and just want to get started with the installation go to:
35 |
36 | :ref:`Step by step Installation guide to make your website fly! `
37 |
38 | Please note that WordPress supports:
39 |
40 | `varnish 3` and `varnish 4`.
41 |
42 | Each new upgrade includes a section about the changes that have been made.
43 |
44 | **We strongly recommend that you upgrade to Varnish 4 as we no longer provide support for Varnish 3.**
45 |
46 | To make your life easier, there is a script:
47 |
48 | VCL Migrator, which can help you upgrade from Varnish 3 to Varnish 4.
49 |
50 | Integration
51 | -----------
52 |
53 | Log in to your WordPress administration page at http://yourdomain.com/wp-admin
54 | using the username and password you configured.
55 |
56 | - Select Plugins
57 | - Add New from the left sidebar menu
58 | - Search for Varnish plugins
59 | - Choose plugin
60 | - Click on Add Plugin
61 | - After the plugin is added, activate plugin
62 |
63 |
64 | Our recommended plugins for WordPress
65 | -------------------------------------
66 |
67 | If you search at WordPress.org for plugins like this:
68 |
69 | .. code-block:: bash
70 |
71 | https://WordPress.org/plugins/search.php?q=varnish+plugins
72 |
73 |
74 | you will be presented with a lot of plugins containing the tag Varnish. But do not
75 | get lost. We have looked through the plugins and below you will find the most
76 | popular ones with a short description.
77 |
78 | The most recommended plugins include:
79 |
80 | - `Varnish HTTP Purge`_
81 |
82 | Varnish HTTP purge sends a PURGE request to the URL of a page or post every time
83 | it it modified. This occurs when editing, publishing, commenting or deleting an
84 | item, and when changing themes. Not all pages are purged every time, depending
85 | on your Varnish configuration. Read more on the link.
86 |
87 | - `W3 Total Cache`_
88 |
89 | W3 total cache improves the user experience of your site by increasing server
90 | performance, reducing the download times and providing transparent content
91 | delivery network (CDN) integration. Read more on the plugins page.
92 |
93 | - `WPBase Cache`_
94 |
95 | The plugin was developed to optimize the WordPress deployment on
96 | varnish + nginx + php-fpm + php-apc server stack using three type of caches full
97 | page cache, db cache and opcode cache. They also support Varnish cache management
98 | with given default.vcl. Read more on the plugins page.
99 |
100 | .. _wp_resources:
101 |
102 | WordPress resources
103 | -------------------
104 |
105 | `How to Purge Varnish`_
106 |
107 | `Optimizing WordPress with Varnish and W3 Total Cache`_
108 |
109 | .. _`How to Purge Varnish`: http://www.dimitri.eu/how-to-purge-varnish-cache/
110 | .. _`Optimizing WordPress with Varnish and W3 Total Cache`: http://code.tutsplus.com/tutorials/optimizing-WordPress-with-varnish-and-w3-total-cache--cms-21136
111 | .. _`W3 Total Cache`: https://WordPress.org/plugins/w3-total-cache/
112 | .. _`Varnish HTTP Purge`: https://WordPress.org/plugins/varnish-http-purge/
113 | .. _`WPBase Cache`: https://WordPress.org/plugins/wpbase-cache/
114 |
--------------------------------------------------------------------------------
/source/content/tutorials/wordpress/wp_vcl.rst:
--------------------------------------------------------------------------------
1 | .. _wp_vcl:
2 |
3 | Some sample VCL for WordPress
4 | =============================
5 |
6 | Ignoring AJAX requests
7 | ......................
8 |
9 | .. code-block:: VCL
10 |
11 | if (req.http.X-Requested-With == "XMLHttpRequest") {
12 | return(pass);
13 | }
14 |
15 | Post requests will not be cached
16 | ................................
17 |
18 | .. code-block:: VCL
19 |
20 | if (req.http.Authorization || req.method == "POST") {
21 | return (pass);
22 | }
23 |
24 | Only caching GET or HEAD requests
25 | .................................
26 |
27 | This makes sure the POST requests are always passed.
28 |
29 | .. code-block:: VCL
30 |
31 | if (req.method != "GET" && req.method != "HEAD") {
32 | return (pass);
33 | }
34 |
35 |
36 | Preventing post and edit pages from being cached
37 | ................................................
38 |
39 | .. code-block:: VCL
40 |
41 | if (req.url ~ "(wp-admin|post\.php|edit\.php|wp-login)") {
42 | return(pass);
43 | }
44 | if (req.url ~ "/wp-cron.php" || req.url ~ "preview=true") {
45 | return (pass);
46 | }
47 |
48 | Remove the "has_js" cookie
49 | ..........................
50 |
51 | .. code-block:: VCL
52 |
53 | set req.http.Cookie = regsuball(req.http.Cookie, "has_js=[^;]+(; )?", "");
54 |
55 |
56 | Remove the wp-settings-1 cookie
57 | ...............................
58 |
59 | .. code-block:: VCL
60 |
61 | set req.http.Cookie = regsuball(req.http.Cookie, "wp-settings-1=[^;]+(; )?", "");
62 |
63 |
64 | Remove the wp-settings-time-1 cookie
65 | ....................................
66 |
67 | .. code-block:: VCL
68 |
69 | set req.http.Cookie = regsuball(req.http.Cookie, "wp-settings-time-1=[^;]+(; )?", "");
70 |
71 |
72 | Remove the wp test cookie
73 | .........................
74 |
75 | .. code-block:: VCL
76 |
77 | set req.http.Cookie = regsuball(req.http.Cookie, "wordpress_test_cookie=[^;]+(; )?", "");
78 |
79 |
80 | Remove the PHPSESSID in members area cookie
81 | ...........................................
82 |
83 | .. code-block:: VCL
84 |
85 | set req.http.Cookie = regsuball(req.http.Cookie, "PHPSESSID=[^;]+(; )?", "");
86 |
87 |
88 | Source: http://www.psynapticmedia.com/varnish-4-example-with-apache-wordpress-woocommerce/
89 | Accessed: 16th August 2016
90 |
--------------------------------------------------------------------------------
/source/image/1-set-page-cache-max-age.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/varnish/varnish-wiki/da3fefba9048552a58cf11e1d97d84defa9ff0e0/source/image/1-set-page-cache-max-age.png
--------------------------------------------------------------------------------
/source/image/2-add-purger.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/varnish/varnish-wiki/da3fefba9048552a58cf11e1d97d84defa9ff0e0/source/image/2-add-purger.png
--------------------------------------------------------------------------------
/source/image/3-http-purger.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/varnish/varnish-wiki/da3fefba9048552a58cf11e1d97d84defa9ff0e0/source/image/3-http-purger.png
--------------------------------------------------------------------------------
/source/image/4-http-purger-request.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/varnish/varnish-wiki/da3fefba9048552a58cf11e1d97d84defa9ff0e0/source/image/4-http-purger-request.png
--------------------------------------------------------------------------------
/source/image/5-http-purger-header-cache-tags.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/varnish/varnish-wiki/da3fefba9048552a58cf11e1d97d84defa9ff0e0/source/image/5-http-purger-header-cache-tags.png
--------------------------------------------------------------------------------
/source/image/config_varnish_admin.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/varnish/varnish-wiki/da3fefba9048552a58cf11e1d97d84defa9ff0e0/source/image/config_varnish_admin.png
--------------------------------------------------------------------------------
/source/image/edit.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/varnish/varnish-wiki/da3fefba9048552a58cf11e1d97d84defa9ff0e0/source/image/edit.png
--------------------------------------------------------------------------------
/source/image/github.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/varnish/varnish-wiki/da3fefba9048552a58cf11e1d97d84defa9ff0e0/source/image/github.png
--------------------------------------------------------------------------------
/source/image/httpcachehit.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/varnish/varnish-wiki/da3fefba9048552a58cf11e1d97d84defa9ff0e0/source/image/httpcachehit.png
--------------------------------------------------------------------------------
/source/image/httpcachemiss.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/varnish/varnish-wiki/da3fefba9048552a58cf11e1d97d84defa9ff0e0/source/image/httpcachemiss.png
--------------------------------------------------------------------------------
/source/image/test.svg:
--------------------------------------------------------------------------------
1 |
2 |
4 |
6 |
7 |
54 |
--------------------------------------------------------------------------------
/source/image/varnishtest_anatomy.dot:
--------------------------------------------------------------------------------
1 | digraph varnishtest {
2 | center=1
3 | rankdir="LR"
4 | client->varnish [ color=red ]
5 | varnish->client [ color=purple ]
6 | varnish->server [ color=purple ]
7 | server->varnish [ color=blue ]
8 |
9 | server [
10 | shape=box
11 | color=blue
12 | label="Server s1"
13 | ]
14 |
15 | varnish [
16 | shape=box
17 | color=purple
18 | label="Varnishtest v1"
19 | ]
20 |
21 | client [
22 | shape=box
23 | color=red
24 | label="Client c1"
25 | ]
26 | }
27 |
--------------------------------------------------------------------------------
/source/image/varnishtest_anatomy.svg:
--------------------------------------------------------------------------------
1 |
2 |
4 |
6 |
7 |
49 |
--------------------------------------------------------------------------------
/source/image/vcl-1.dot:
--------------------------------------------------------------------------------
1 |
2 | digraph v_center {
3 | center=1
4 |
5 | vcl_recv->vcl_pass [ label="pass" weight=1 color=red ]
6 | vcl_recv->vcl_hash [ label="lookup" weight=4 color=green style=bold ]
7 |
8 | vcl_hash->lookup [ label="hash" weight=4 color=green style=bold ]
9 | lookup->vcl_hit [ label="yes" weight=4 color=green style=bold ]
10 | lookup->vcl_miss [ label="no" weight=1 color=blue ]
11 |
12 | vcl_hit->vcl_deliver [ label="deliver" weight=3 color=green style=bold ]
13 | vcl_miss->fetch [ label="fetch" weight=3 color=blue ]
14 | vcl_pass->fetch [ label="fetch" weight=1 color=red ]
15 | fetch->vcl_fetch [ weight=2 ]
16 |
17 | vcl_fetch->cache [ label="deliver" ]
18 | vcl_fetch->dont_cache [ label="pass" color=red ]
19 | cache->vcl_deliver [ weight=1 ]
20 | dont_cache->vcl_deliver [ color=red ]
21 |
22 | client->vcl_recv [ weight=4 ]
23 | vcl_deliver->client
24 |
25 | fetch->backend
26 | backend->fetch
27 |
28 | dont_cache [
29 | shape=diamond
30 | label="Don't cache"
31 | ]
32 |
33 | cache [
34 | shape=diamond
35 | label="Cache"
36 | ]
37 | lookup [
38 | shape=diamond
39 | label="Is the object in cache?"
40 | ]
41 |
42 | fetch [
43 | shape=diamond
44 | label="Fetch object from backend"
45 | ]
46 |
47 | client [
48 | shape=box
49 | label="Client"
50 | ]
51 |
52 | backend [
53 | shape=box
54 | label="Backend server"
55 | ]
56 | }
57 |
--------------------------------------------------------------------------------
/source/image/vcl-1.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/varnish/varnish-wiki/da3fefba9048552a58cf11e1d97d84defa9ff0e0/source/image/vcl-1.png
--------------------------------------------------------------------------------
/source/index.rst:
--------------------------------------------------------------------------------
1 | .. Varnish Documentation documentation master file, created by
2 | sphinx-quickstart on Mon Jun 27 08:27:58 2016.
3 | You can adapt this file completely to your liking, but it should at least
4 | contain the root `toctree` directive.
5 |
6 | Varnish Web Developer Wiki
7 | ==========================
8 |
9 | In this wiki we have gathered in one place the best community resources that we
10 | could find that you will need to start using Varnish. Let's get you started from
11 | development to production!
12 |
13 | Varnish is very flexible and as such can be used as a **caching engine** , a
14 | **load balancer** , a **web application firewall**, an **edge authentication**
15 | and **authorization mechanism**. Other use cases are **HTTP routing**,
16 | **hotlinking protection**, **DDoS attack defender** and, a lot, more.
17 |
18 | Varnish is a reverse-proxy HTTP accelerator designed for heavily consumed API
19 | endpoints and also for dynamic, heavy-content, high-traffic websites. It is
20 | currently used by the likes of Facebook, Wikipedia, Vimeo, Twitter, Tumblr, The
21 | Guardian, VG.no and many others. More than 2.5 million sites run the software.
22 |
23 | +----------------------------------------+----------------------------------------+
24 | | |varnishstarttext|_ | |webdevfaqtext|_ |
25 | +----------------------------------------+----------------------------------------+
26 |
27 | Tutorials
28 | .........
29 |
30 | +----------------------------------------+----------------------------------------+
31 | | |varnishanytext|_ | |wordpresstext|_ |
32 | +----------------------------------------+----------------------------------------+
33 | | |drupaltext|_ | |magentotext|_ |
34 | +----------------------------------------+----------------------------------------+
35 |
36 |
37 | .. toctree::
38 | :hidden:
39 |
40 | /start/index
41 | /faq/index
42 | /content/tutorials/varnish/index
43 | /content/tutorials/wordpress/index
44 | /content/tutorials/magento2/index
45 | /content/tutorials/drupal/index
46 | /content/tutorials/aem
47 | /content/tutorials/expressionEngine
48 | /content/tutorials/sitecoreCMS
49 |
50 | .. |varnishstarttext| replace:: **Getting Started with Varnish!**
51 | .. _varnishstarttext: ./start/index.html
52 |
53 | .. |webdevfaqtext| replace:: **Varnish Web Developer FAQ**
54 | .. _webdevfaqtext: ./faq/index.html
55 |
56 | .. |varnishanytext| replace:: **Varnish Your Site Now**
57 | .. _varnishanytext: ./content/tutorials/varnish/index.html
58 |
59 | .. |wordpresstext| replace:: **Wordpress with Varnish**
60 | .. _wordpresstext: ./content/tutorials/wordpress/index.html
61 |
62 | .. |drupaltext| replace:: **Drupal with Varnish**
63 | .. _drupaltext: ./content/tutorials/drupal/index.html
64 |
65 | .. |magentotext| replace:: **Magento2 with Varnish**
66 | .. _magentotext: ./content/tutorials/magento2/index.html
67 |
--------------------------------------------------------------------------------
/source/start/image:
--------------------------------------------------------------------------------
1 | /home/syeda/vagrant/varnish-wiki/source/image
--------------------------------------------------------------------------------
/source/start/index.rst:
--------------------------------------------------------------------------------
1 | .. _start:
2 |
3 | Getting started
4 | ===============
5 |
6 | .. toctree::
7 | :hidden:
8 |
9 | your_varnish_goals
10 | website_arch
11 | httpcaching_basics
12 | webTerms
13 | general_resources
14 |
15 |
16 | Let's get started with Varnishing your website!
17 |
18 | Varnish Software Training
19 | .........................
20 |
21 | `Free E-learning course: Getting started with Varnish `_
22 |
23 | `Varnish Software Course Calendar `_
24 |
25 |
26 | Installing and configuring Varnish
27 | ..................................
28 |
29 | :doc:`Installing Varnish `
30 |
31 | :doc:`How to VCL? `
32 |
33 | :doc:`Test Varnish with VarnishTest `
34 |
35 | :doc:`Easy piece of advice `
36 |
37 | :doc:`What do you want to achieve for your site? `
38 |
39 |
40 | Step-by-step configuration for web applications
41 | ...............................................
42 |
43 | :doc:`Magento 2 guide to Varnish `
44 |
45 | :doc:`WordPress guide to Varnish `
46 |
47 | :doc:`Drupal guide to Varnish `
48 |
49 |
50 | Configuration for enterprise products
51 | .....................................
52 |
53 | :doc:`Adobe Extension Manager (AEM) `
54 |
55 | :doc:`Expression Engine (EE) `
56 |
57 |
58 | Configuring VCL beyond the default
59 | ..................................
60 |
61 | Below are links to examples of VCL configurations in/with Varnish.
62 |
63 | :doc:`What's in the built-in VCL? `
64 |
65 | :doc:`Common VCL configuration `
66 |
67 | :doc:`WordPress and VCL `
68 |
69 | :doc:`Drupal and VCL `
70 |
71 | :doc:`Magento2 and VCL `
72 |
73 |
74 | Recipes for cache invalidation
75 | ..............................
76 |
77 | `Our Webinar on Cache Invalidation Strategies`_
78 |
79 | :doc:`Cache Invalidation Bundle `
80 |
81 |
82 | Below is a list of resources that can help you understand and manage Varnish better:
83 |
84 | 1. `The Varnish Book`_ - The book is one of our best training manuals/reference sources, which includes in-depth details and exercises.
85 | 2. `Getting started with Varnish Cache`_ - This guide helps you master Varnish basics so you can get up and running in no time - without the steep learning curve.
86 | 3. `The Varnish Tutorial`_ - The tutorial explains Varnish basics and gets you started with Varnish.
87 | 4. `The Varnish User Guide`_ - The user guide explains how Varnish works and how you can use it to improve your website.
88 | 5. `The Varnish Reference Manual`_ - The reference manual contains hard facts and is useful for looking up specific questions.
89 | 6. :doc:`Relevant Resources ` - The resources document contains links to useful information collected from sources outside our website.
90 |
91 | **Last but not least this wiki will give you a hands-on guide to making your digital content fly!**
92 |
93 | .. _`The Varnish Book`: http://book.varnish-software.com/4.0/
94 | .. _`The Varnish Tutorial`: https://www.varnish-cache.org/docs/4.1/tutorial/index.html#tutorial-index
95 | .. _`The Varnish User Guide`: https://www.varnish-cache.org/docs/4.1/users-guide/index.html#users-guide-index
96 | .. _`The Varnish Reference Manual`: https://www.varnish-cache.org/docs/4.1/reference/index.html#reference-index
97 | .. _`Our Webinar on Cache Invalidation Strategies`: https://info.varnish-software.com/webinars_fm/cache-invalidation-strategies
98 | .. _`Getting started with Varnish Cache`: https://info.varnish-software.com/getting-started-with-varnish-cache-oreilly-book
99 |
--------------------------------------------------------------------------------
/source/start/tables:
--------------------------------------------------------------------------------
1 | /home/syeda/vagrant/varnish-wiki/source/tables
--------------------------------------------------------------------------------
/source/start/webTerms.rst:
--------------------------------------------------------------------------------
1 | .. _webTerms:
2 |
3 |
4 | Web-caching terminology
5 | =========================
6 |
7 | **backend**
8 | The HTTP server varnishd is caching for. This can be any sort of device that
9 | handles HTTP requests, including, but not limited to: a web server, a CMS, a
10 | load balancer, another varnishd, etc.
11 |
12 | **backend response**
13 | The response specifically served from a backend to varnishd. The backend
14 | response may be manipulated in vcl_backend_response.
15 |
16 | **body**
17 | The bytes that make up the contents of the object, varnishd does not care if
18 | they are in HTML, XML, JPEG or even EBCDIC; to varnishd they are just bytes.
19 |
20 | **client**
21 | The program that sends varnishd an HTTP request, typically a browser, but do
22 | not forget to think about spiders, robots, script-kiddies and criminals.
23 |
24 | **cache**
25 | A collection of relevant data stored away for reuse.
26 |
27 | **cookie:**
28 | A cookie is not just a sweet biscuit anymore. Cookies are actually packets of data sent
29 | by the web server to a browser and stored there. It is later used to identify the
30 | user when he/she revisits the same server.
31 |
32 | **domain:**
33 | The domain is an area or territory on the internet, which can be owned by a user or
34 | company.
35 |
36 | **ESI:**
37 | Edge Side Includes is a small markup language and helps in handling web
38 | infrastructure scaling.
39 |
40 | **header**
41 | An HTTP protocol header, like "Accept-Encoding:".
42 |
43 | **hit**
44 | An object Varnish delivers from cache.
45 |
46 | **hit rate:**
47 | The rate at which Varnish delivers an object from cache.
48 |
49 | **HTTP**
50 | Hyper Text Transfer Protocol is an application protocol for hypermedia
51 | information systems.
52 |
53 | **HTTP2**
54 | HTTP2 is basically the same as HTTP1.1, the major difference being that HTTP2 can
55 | befriend new web applications by speeding up how data is framed (also secured)
56 | and transported between the client and the server.
57 |
58 | **master (process)**
59 | One of the two processes in the varnishd program. The master process is a
60 | manager/nanny process that handles configuration, parameters, compilation of
61 | :term:VCL etc. but it never gets near actual HTTP traffic.
62 |
63 | **miss**
64 | An object Varnish fetches from the backend before it is served to the client.
65 | The object may or may not be put in the cache; it depends on the content.
66 |
67 | **object**
68 | The (possibly) cached version of a backend response. varnishd receives a
69 | response from the backend and creates an object, from which it may deliver
70 | cached responses to clients. If the object is created as a result of a request
71 | which is passed, it will not be stored for caching.
72 |
73 | **optimize**
74 | Optimize is the mechanism of improving the way data is retrieved.
75 |
76 | **pass**
77 | A pass is an object Varnish does not try to cache, but simply fetches from the backend and
78 | hands to the client.
79 |
80 | **pipe**
81 | Varnish just moves the bytes between client and backend; it does not try to
82 | understand what they mean.
83 |
84 | **request**
85 | What the client sends to varnishd and varnishd sends to the backend.
86 |
87 | **response**
88 | What the backend returns to varnishd and varnishd returns to the client.
89 | When the response is stored in varnishd's cache, we call it an object.
90 |
91 | **tag**
92 | A set of characters added to data to identify it individually.
93 |
94 | **timeout:**
95 | A predefined interval of time that has expired.
96 |
97 | **traffic:**
98 | The amount of requests or responses on the line
99 |
100 | **varnishd** (NB: with 'd')
101 | This is the actual Varnish cache program. There is only one program, but when
102 | you run it, you will get two processes: The "master" and the "worker"
103 | (or "child").
104 |
105 | **varnishhist**
106 | Eye-candy program showing response time histogram in 1980s ASCII-art style.
107 |
108 | **varnishlog**
109 | Program which presents Varnish transaction log in native format.
110 |
111 | **varnishncsa**
112 | Program which presents Varnish transaction log in "NCSA" format.
113 |
114 | **varnishstat**
115 | Program which presents Varnish statistics counters.
116 |
117 | **varnishtest**
118 | Program to test varnishd's behavior with, it simulates backend and client
119 | according to test scripts.
120 |
121 | **varnishtop**
122 | Program which gives real-time "top-X" list view of transaction log.
123 |
124 | **web server**
125 | A web server is a machine that runs a software that uses HTTP (Hypertext Transfer
126 | Protocol) to serve the files in the form of web pages, in response to their
127 | requests, which are forwarded by their computers' HTTP clients.
128 |
129 | **web page**
130 | A page generated or written from a web application.
131 |
132 | **worker (process)**
133 | The worker process is started and configured by the master process. This is the
134 | process that does all the work you actually want Varnish to do. If the worker
135 | dies, the master will try start it again, to keep your website alive.
136 |
137 | Varnish three-letter acronyms
138 | =============================
139 |
140 | You will find these acronyms used when you use any of our Varnish-related
141 | documentation, the main website, book, wiki, etc.
142 |
143 | **VAV**
144 | Varnish Arg Vector -- Argv parsing.
145 |
146 | **VBE**
147 | Varnish backend -- Code for contacting backends (bin/varnishd/cache_backend.c)
148 |
149 | **VBP**
150 | Varnish Backend Polling -- Health checks of backends
151 | (bin/varnishd/cache_backend_poll.c)
152 |
153 | **VCA**
154 | Varnish Connection Acceptor -- The code that receives/accepts the TCP
155 | connections (bin/varnishd/cache_acceptor.c)
156 |
157 | **VCC**
158 | VCL to C Compiler -- The code that compiles VCL to C code. (lib/libvcl)
159 |
160 | **VCL**
161 | Varnish Configuration Language -- The domain-specific programming language used
162 | for configuring a varnishd.
163 |
164 | **VCT**
165 | Varnish CType(3) -- Character classification for RFC2616 and XML parsing.
166 |
167 | **VDD**
168 | Varnish (Core) Developer Day -- Quarterly invite-only meeting strictly for
169 | Varnish core (C) developers, packagers and VMOD hackers.
170 |
171 | **VEV**
172 | Varnish EVent -- library functions to implement a simple event dispatcher.
173 |
174 | **VGB**
175 | Varnish Governing Board -- May or may not exist. If you need to ask, you are not
176 | on it.
177 |
178 | **VGC**
179 | Varnish Generated Code -- Code generated by VCC from VCL.
180 |
181 | **VIN**
182 | Varnish Instance Naming -- Resolution of -n arguments.
183 |
184 | **VLU**
185 | Varnish Line Up -- library functions to collect stream of bytes into lines for
186 | processing. (lib/libvarnish/vlu.c)
187 |
188 | **VRE**
189 | Varnish Regular Expression -- library functions for regular expression based
190 | matching and substring replacement. (lib/libvarnish/vre.c)
191 |
192 | **VRT**
193 | Varnish Run Time -- functions called from compiled code. (bin/varnishd/cache_vrt.c)
194 |
195 | **VRY**
196 | VaRY -- Related to processing of Vary: HTTP headers. (bin/varnishd/cache_vary.c)
197 |
198 | **VSL**
199 | Varnish shared memory Log -- The log written into the shared memory segment for
200 | varnish{log,ncsa,top,hist} to see.
201 |
202 | **VSB**
203 | Varnish string buffer -- a copy of the FreeBSD "sbuf" library, for safe string
204 | handling.
205 |
206 | **VSC**
207 | Varnish Statistics Counter -- counters for various stats, exposed via varnishapi.
208 |
209 | **VSS**
210 | Varnish Session Stuff -- library functions to wrap DNS/TCP. (lib/libvarnish/vss.c)
211 |
212 | **VTC**
213 | Varnish Test Code -- a test-specification for the varnishtest program.
214 |
215 | **VTLA**
216 | Varnish three-letter acronym -- No rule without an exception.
217 |
218 | **VUG**
219 | Varnish User Group meeting -- Half-yearly event where the users and developers
220 | of Varnish Cache gather to share experiences and plan future development.
221 |
222 | **VWx**
223 | Varnish Waiter 'x' -- A code module to monitor idle sessions.
224 |
225 | **VWE**
226 | Varnish Waiter Epoll -- epoll(2) (linux) based waiter module.
227 |
228 | **VWK**
229 | Varnish Waiter Kqueue -- kqueue(2) (freebsd) based waiter module.
230 |
231 | **VWP**
232 | Varnish Waiter Poll -- poll(2) based waiter module.
233 |
234 | **VWS**
235 | Varnish Waiter Solaris -- Solaris ports(2) based waiter module.
236 |
--------------------------------------------------------------------------------
/source/start/website_arch.rst:
--------------------------------------------------------------------------------
1 | .. _website_arch:
2 |
3 | Understanding a typical website architecture
4 | ============================================
5 |
6 | Regardless of the web application you use to manage your website, most websites
7 | follow a similar pattern.
8 |
9 | Each website has a few distinguishable sections:
10 |
11 | - A front page
12 | - Articles or sub pages
13 | - A login box
14 | - Static elements like CSS, JavaScript, graphics, etc.
15 |
16 |
17 | Easy advice on caching your website?
18 | ....................................
19 |
20 | - For static websites, cache contents for user not logged in.
21 | - For dynamic websites:
22 | * First you have to be able to isolate each component.
23 | * Then choose which component to cache.
24 | * Decide for how long to cache.
25 |
26 | This is where Varnish can really help you. Varnish assigns every single object a
27 | TTL value. Here we discuss how each of the components can be managed separately yet
28 | displayed together on a web page.
29 |
30 | Cookies
31 | .......
32 |
33 | By default Varnish does not cache a page if it has header fields from clients or
34 | servers. The main reason for this is to avoid delivering cookie-based content to
35 | the wrong client and also to avoid clogging the cache with copies of the same
36 | content.
37 |
38 | Most importantly, when dealing with caching cookies, caching anything including
39 | personal client information is discouraged, as it can jeopardize a
40 | client or your company if delivered to the wrong client.
41 |
42 | One of our recommended VMODs for handling cookies is `libvmod-cookie`_ which
43 | is available in the Varnish module repository on `github`_ or you can download
44 | the whole module from the `varnish website`. The module also contains a `vmod-header`
45 | which can be used for manipulation of duplicated HTTP headers, such as multiple
46 | set-cookie headers!
47 |
48 |
49 | Edge Side Includes
50 | ..................
51 |
52 | Edge Side Includes (ESI) helps Varnish deliver various objects together.
53 | On a Magento website, for example, a good use of ESI would be to display new products on a top banner on a client home page or cart.
54 | While most of the client home page content can be cached, the top banner and
55 | the cart will have smaller TTL values.
56 | Let's say the TTL value of the banner would be about 5 minutes, the cart about
57 | 1 hour while the user-page content, such as name, purchased products, watching or
58 | history would be cached for a day.
59 |
60 |
61 | AJAX requests on Magento
62 | ........................
63 |
64 | AJAX is of course a cool technology and developers love it.
65 | If you are a long-term Magento user you probably added them to your Magento site
66 | to avoid page reloads or partial page reloads. Of course you have already read
67 | about ESIs and how they can do a similar task for you.
68 |
69 | But if you already have AJAX on your Magento site, you should know that there are
70 | browser restrictions that do not allow AJAX to send requests across another domain.
71 | What you can do to solve this issue is to masquerade all AJAX requests. To be able
72 | to do that you will need to add a regular expression to masquerade the request URL
73 | in the VCL code in the `vcl_recv` subroutine.
74 |
75 | .. literalinclude:: /content/examples/snippet6_masq
76 | :language: VCL
77 |
78 | .. _`libvmod-cookie`: https://download.varnish-software.com/varnish-modules/varnish4.0/libvmod-cookie-20151013.git7e453b4.tar.gz
79 | .. _`github`: https://github.com/varnish/varnish-modules
80 | .. _`varnish website`: https://download.varnish-software.com/varnish-modules/
81 |
--------------------------------------------------------------------------------
/source/tables/cachecontrol_arg.csv:
--------------------------------------------------------------------------------
1 | Argument,Request,Response
2 | no-cache,X,X
3 | no-store,X,X
4 | max-age,X,X
5 | s-maxage, ,X
6 | max-stale,X,
7 | min-fresh,X,
8 | no-transform,X,X
9 | only-if-cached,X,
10 | public, ,X
11 | private, ,X
12 | must-revalidate, ,X
13 | proxy-revalidate, ,X
14 |
--------------------------------------------------------------------------------
/source/tables/http_headers.csv:
--------------------------------------------------------------------------------
1 |
2 | Header, Request, Response
3 | Expires, X
4 | Cache-Control, X, X
5 | Last-Modified , X
6 | If-Modified-Since, X
7 | If-None-Match, X
8 | Etag, X
9 | Pragma, X, X
10 | Vary, X
11 | Age, X
12 |
--------------------------------------------------------------------------------
 }}){kind=logo}
74 |
75 |
76 | 
79 |
80 | 
11 |
12 | 
18 |
19 |