diff --git a/appendix-d.rst b/appendix-d.rst index cd00f82..f761cce 100644 --- a/appendix-d.rst +++ b/appendix-d.rst @@ -52,7 +52,7 @@ may want with Varnish. # This changes /foo/bar/foo/blatti to /bar/bar/bar/blatti. set req.url = regsuball(req.url, "foo","bar"); - # Paranthesis can be used to group logic, and | as a logical + # Parentheses can be used to group logic, and | as a logical # "or" operator. if (req.url ~ "^/(html|css|img)") { # Matches /html, /css and /img @@ -67,7 +67,7 @@ may want with Varnish. # puts it into a request header called "x-magic". # It does this by first ensuring we've passed the question-mark, # then skipping all characters up until "magic=", then starting - # a group using paranthesis. The content of the group is one or + # a group using parentheses. The content of the group is one or # more of any character except &. # + acts just like * , but where * means "0 or more", + means "1 # or more" diff --git a/chapter-1.rst b/chapter-1.rst index 4a8cd5e..9312e31 100644 --- a/chapter-1.rst +++ b/chapter-1.rst @@ -133,7 +133,7 @@ development power to implement them, but they did not necessarily align with the goals and time frames of Varnish Cache. Varnish Plus became a commercial test-bed for features that were not *yet* in Varnish Cache for various reasons. As time passed, many of the features that begun life in -Varnish Plus have trickled into Varnish Cache proper in one way or an other +Varnish Plus have trickled into Varnish Cache proper in one way or another (streaming, surrogate keys, and more), and some have still to make it. Some may never make it. This book focuses on Varnish Cache proper, but will reference Varnish Plus where it makes sense. @@ -200,7 +200,7 @@ called "The Varnish Book" (Not to be confused with THIS book about Varnish). This is available freely through their site at http://varnish-software.com, after registration. -An other less known source of information for Varnish is the flow +Another less known source of information for Varnish is the flow charts/``dot``-graphs used to document the VCL state engine. The only official location for this is found in the source code of Varnish, under ``doc/graphviz/``. They can be generated, assuming you have diff --git a/chapter-2.rst b/chapter-2.rst index c0e1118..ef0d97a 100644 --- a/chapter-2.rst +++ b/chapter-2.rst @@ -28,7 +28,7 @@ Tools: The browser ------------------ A browser is an important tool. Most of todays web traffic is, -unsurprisingly, through a web browser. Therefor, it is important to be able +unsurprisingly, through a web browser. Therefore, it is important to be able to dig deeper into how they work with regards to cache. Most browsers have a developer- or debug console, but we will focus on Chrome. @@ -221,7 +221,7 @@ Adding other headers is done the same way:: We just simulated what our browser did, and verified that it really was the ``If-Modified-Since`` header that made the difference earlier. To have -multiple headers, just list them one after an other:: +multiple headers, just list them one after another:: $ http -p Hh http://kly.no/ "Host: example.com" "User-Agent: foo" "X-demo: bar" GET / HTTP/1.1 @@ -421,7 +421,7 @@ If a server sends a ``Last-Modified``-header, the client can issue a indicating that the server only needs to transmit the response body if it's been updated. -Some times it isn't trivial to know the modification time, but you might be +Sometimes it isn't trivial to know the modification time, but you might be able to uniquely identify the content anyway. For that matter, the content might have been changed back to a previous state. This is where the *entity tag*, or ``ETag`` response header is useful. @@ -717,7 +717,7 @@ for Varnish, and is covered detailed in later chapters. For now, it's good to just get used to issuing an extra request to Varnish after the expiry time to see the update take place. -Let's do an other example of this, using a browser, and 60 seconds of max +Let's do another example of this, using a browser, and 60 seconds of max age and an ETag header set to something random so our browser can do conditional GET requests: @@ -1260,7 +1260,7 @@ details. The ``Vary`` header simply states that any variation in the request header, however small, mandates a new object in the cache. This causes numerous headaches. Here are some examples: -- ``Accept-Enoding: gzip,deflate`` and ``Accept-Encoding: deflate,gzip`` +- ``Accept-Encoding: gzip,deflate`` and ``Accept-Encoding: deflate,gzip`` will result in two different variants. - ``Vary: User-Agent`` will cause a tremendous amount of variants, since the level of detail in modern ``User-Agent`` headers is extreme. @@ -1269,7 +1269,7 @@ causes numerous headaches. Here are some examples: Many of these things can be remedied or at least worked around in Varnish. All of it will be covered in detail in separate chapters. -On a last note, Varnish has a special case were it refuse to cache any +On a last note, Varnish has a special case where it refuses to cache any content with a response header of ``Vary: *``. Request methods @@ -1326,14 +1326,14 @@ Varnish:: 127.0.0.1 - - [28/Nov/2015:00:32:05 +0000] "GET /cgi-bin/foo.sh HTTP/1.1" 200 163 "-" "HTTPie/0.8.0" The client sees the same result, but the web server has logged a ``GET`` -request. Please note that ``HEAD``-requests include a ``Content-Lenght`` as +request. Please note that ``HEAD``-requests include a ``Content-Length`` as if a ``GET``-request was issued. It is only the response body itself that is absent. Cached status codes ------------------- -Only a subset of response odes allow cacheing, even if an ``s-maxage`` or +Only a subset of response codes allow caching, even if an ``s-maxage`` or similar is provided. Quoting directly from Varnish source code, specifically ``bin/varnishd/cache/cache_rfc2616.c``, the list is:: @@ -1381,7 +1381,7 @@ Cookies and authorization Requests with a cookie-header or HTTP basic authorization header are tricky at best to cache. Varnish takes a "better safe than sorry" approach, and -does not cache responses to requests with either a ``Cookie``-header, +does not cache responses to requests with either a ``Cookie``-header or ``Authorization``-header by default. Responses with ``Set-Cookie`` are not cached. diff --git a/chapter-3.rst b/chapter-3.rst index 125c42f..2680d51 100644 --- a/chapter-3.rst +++ b/chapter-3.rst @@ -65,7 +65,7 @@ which is typically about 85MB large. It is split in two parts. The smallest bit is the part for counters, used to keep track of any part of Varnish that could be covered by a number, e.g. number of cache hits, number of objects, and so forth. This part of the shmlog is roughly 2MB by -default, by varies depending on setup. +default, but varies depending on setup. The biggest part of the shmlog is reserved for fifo-style log entries, directly related to requests typically. This is 80MB by default. Once those @@ -99,7 +99,7 @@ Varnish will abort. In most cases, that means the entire child process shuts down, only to have the manager start it back up. You lose all connections, you lose all cache. -Hopefully, you wont run into assert errors. They are there to handle what +Hopefully, you won't run into assert errors. They are there to handle what is believed to be the unthinkable. A more realistic example can be: - Create an object, called *foo*. Set ``foo.magic`` to ``0x123765``. @@ -628,9 +628,9 @@ If you just type ``varnishadm``, you enter the interactive mode:: Closing CLI connection Both modes are functionally identical. One benefit of using the interactive -mode is that you don't have to worry about yet an other level of quotation +mode is that you don't have to worry about yet another level of quotation marks once you start dealing with more complex commands than ``vcl.load`` -and ``param.list``. For now, it's just a matter of style. An other +and ``param.list``. For now, it's just a matter of style. Another difference is that ``varnishadm`` in interactive mode also offer rudimentary command line completion, something your shell might not. @@ -675,8 +675,8 @@ It can also be accessed in manners better suited for scripting, either -x`` (XML). The real-time mode collects data over time, to provide you with meaningful interpretation. Knowing that you have had 11278670 cache hits over the last six and a half days might be interesting, but knowing that -you have 25.96 cache hits per seconds right now is far more useful. The -same can be achieved through ``varnishtat -1`` and similar by executing the +you have 25.96 cache hits per second right now is far more useful. The +same can be achieved through ``varnishstat -1`` and similar by executing the command twice and comparing the values. Looking at the upper left corner of the screenshot above, you'll see some @@ -719,7 +719,7 @@ The main area shows 7 columns: and similar. ``CHANGE`` - "Change per second". Or put an other way: The difference between + "Change per second". Or put another way: The difference between the current value and the value read a second earlier. Can be read as "cache hit per second" or "client reuqests per second". @@ -836,7 +836,7 @@ traffic for that to be useful. You need to be able to filter and group data to be able to use ``varnishlog`` productively. Normally ``varnishlog`` will only parse new data. Since the shmlog contains -up to 80MB of old data, it's some times useful to look at this data too. +up to 80MB of old data, it's sometimes useful to look at this data too. This can be achieved with the ``-d`` argument. You can also select if you want backend-traffic (``-b``), client-traffic @@ -901,7 +901,7 @@ log entries. The very first column is used to help you group requests. The single ``*`` tells you that this particular line is just informing you about the following grouping. ``<< Request >> 2`` tells you that the following is -grouped as a request, and the *vxid* is 2. A *vixid* is an ID attached to +grouped as a request, and the *vxid* is 2. A *vxid* is an ID attached to all log records. You will also see it in the response header ``X-Varnish``. Next, you see what is more typical entries. Each log line starts with a @@ -1125,7 +1125,7 @@ Using a VSL query with ``-g raw`` will be similar to ``-i`` or ``-I``:: # varnishlog -d -g raw -q 'ReqUrl eq "/"' 2 ReqURL c / -An other option for grouping is ``-g session``. This will behave similar to +Another option for grouping is ``-g session``. This will behave similar to ``-g request`` for many tests, but it's for a single HTTP session. Or in other words: If a client re-uses a connection to issue multiple HTTP requests, ``-g request`` will separate each request, but ``-g session`` @@ -1226,7 +1226,7 @@ matching using ``~`` for comparison:: ::1 - - [18/Dec/2015:14:23:42 +0000] "GET http://localhost/?30808 HTTP/1.1" 200 3092 "-" "HTTPie/0.8.0" (...) -An other helpful way to use a VSL query is to investigate the details of +Another helpful way to use a VSL query is to investigate the details of the ``Timestamp`` tag. Quoting directly from the ``vsl(7)`` manual page:: Timestamp - Timing information @@ -1309,7 +1309,7 @@ will match if ``Timestamp[3]`` is 1.006334, as seen here, but ``Timestamp[3] > 1`` will not, because it will be considered the same as ``1 > 1``. In short: Use ``1.0`` instead of just ``1``. -An other nifty way to use VSL queries is to investigate the ``TTL`` tag. +Another nifty way to use VSL queries is to investigate the ``TTL`` tag. This log tag is used to report how an object gets its cache duration:: # varnishlog -g raw -d -i TTL @@ -1368,7 +1368,7 @@ seconds. Let's try to modify some headers from a backend and try again:: - End You can still see the ``TTL`` header, but now it reads 3600. -Unfortunately, there's a miss-match between the documentation and +Unfortunately, there's a mismatch between the documentation and implementation in Varnish 4.0 and 4.1. The documentation suggests that the first number should take ``Age`` into account, but as we just demonstrated, that is clearly not happening (if it was, then the first @@ -1425,7 +1425,7 @@ Combining multiple queries is also possible:: These examples are mostly meant to get you started and give you an idea of what you can do. The best reference pages for these tools are the manual pages, and the ``vsl-query(7)`` and ``vsl(7)`` manual pages. Even if they -some times do get out of date. +sometimes do get out of date. Summary ------- @@ -1442,10 +1442,10 @@ scripts, the default values are tuned for real web sites and can be used even on quite high-traffic sites. Of the tools demonstrated here, ``varnishlog``, ``varnishadm`` and -``varnishstat`` are the real work horses. Mastering a few simple VSL +``varnishstat`` are the real workhorses. Mastering a few simple VSL queries will make operating on the shared memory log a breeze, even when your site is serving thousands of requests per second and you need to find -that one URL that's miss-behaving. +that one URL that's misbehaving. When you are introduced to the Varnish Configuration Language in the chapters to come, these tools will be right at the center of your work diff --git a/chapter-4.rst b/chapter-4.rst index 2cca075..07cde80 100644 --- a/chapter-4.rst +++ b/chapter-4.rst @@ -11,7 +11,7 @@ Introducing VCL removed. That said, the content itself is correct and you are welcome to read it - and coment. + and comment. The Varnish Configuration Language is a small custom programming language that gives you the mechanism to hook into Varnish's request handling state @@ -61,7 +61,7 @@ incorrectly due to re-write rules, then fix your rules but find the old content due to the previously wrong VCL. Reloading VCL is always done through the CLI, but most startup scripts -provide shorthands that does the job for you. You can do it manually using +provide shorthands that do the job for you. You can do it manually using ``varnishadm``:: # varnishadm vcl.list @@ -263,13 +263,13 @@ greatly. * like this.*/ # Remember, always start with "vcl 4.0;". The VCL version. Even in - # Varnsih 4.1 + # Varnish 4.1 vcl 4.0; # White space is largely optional backend foo{.host="localhost";.port="80";} - # vcl_recv is an other VCL state you can modify. It is the first + # vcl_recv is another VCL state you can modify. It is the first # one in the request chain, and we will discuss it in great detail # shortly. sub vcl_recv { @@ -303,11 +303,11 @@ greatly. set req.http.X-foo = regsuball(req.url,"foo","bar"); } - # You can define your own sub routines, but they can't start with + # You can define your own subroutines, but they can't start with # vcl_. Varnish reserves all VCL function names that start with - # vcl_ for it self. + # vcl_ for itself. sub check_request_method { - # Custom sub routines can be accessed anywhere, as long as + # Custom subroutines can be accessed anywhere, as long as # the variables and return methods used are valid where the # subroutine is called. if (req.method == "POST" || req.method == "PUT") { @@ -348,12 +348,12 @@ greatly. } # The Host header contains the verbatim Host header, as - # supplied by the client. Some times, that includes a port + # supplied by the client. Sometimes, that includes a port # number, but typically only if it is user-visible (e.g.: # the user entered http://www.example.com:8080/) if (req.http.host == "www.example.com" && req.url == "/login") { - # return (pass) is an other return statement. It - # instructs Varnish to by-pass the cache for this + # return (pass) is another return statement. It + # instructs Varnish to bypass the cache for this # request. return (pass); } @@ -373,7 +373,7 @@ greatly. More on return-statements ------------------------- -A central mechanism of VCL is the return-statement, some times referred to +A central mechanism of VCL is the return-statement, sometimes referred to as a terminating statement. It is important to understand just what this means. @@ -525,7 +525,7 @@ perfect cache hit rate. Walking through the list from the top, it starts out by checking if the request method is ``PRI``, which is a request method for the SPDY protocol, -and/or HTTP/2.0. This is currently unsuported, so Varnish terminates the +and/or HTTP/2.0. This is currently unsupported, so Varnish terminates the VCL state with a ``synth(405)``. This will cause Varnish to synthesize an error message with a pre-set @@ -573,8 +573,8 @@ To summarize the built in VCL: - Reject SPDY / HTTP/2.0 requests - Pipe unknown (possibly unsafe) request methods directly to the backend -- By-pass cache for anything except ``GET`` and ``HEAD`` requests -- By-pass cache for requests with ``Authorization`` or ``Cookie`` headers. +- Bypass cache for anything except ``GET`` and ``HEAD`` requests +- Bypass cache for requests with ``Authorization`` or ``Cookie`` headers. And the return states that are valid are: @@ -623,7 +623,7 @@ changing one of them to the other. This is quite easy in VCL. } Notice how the above VCL split the logically separate problems into two -different sub routines. We could just as easily have placed them both +different subroutines. We could just as easily have placed them both directly in `vcl_recv`, but the above form will yield a VCL file that is easier to read and organize over time. @@ -1342,7 +1342,7 @@ hit, the value will be 1 or greater. Other than `obj.hits` and `obj.uncacheable`, you do not have direct access to the object. You do, however, have most of what you need in `resp.*`. The cached object is always read-only, but the `resp` data structure represents -this specific response, not the cached object it self. As such, you can +this specific response, not the cached object itself. As such, you can modify it. The `obj.uncacheable` variable can be used to identify if the response was @@ -1375,7 +1375,7 @@ It is also worth remembering that multiple client threads can be waiting for the same object to be fetched by a single backend thread. But despite all this, the basic VCL of the backend fetcher is pretty -straight forward, with one or two minor exceptions. +straightforward, with one or two minor exceptions. `vcl_backend_fetch` ................... @@ -1388,7 +1388,7 @@ straight forward, with one or two minor exceptions. | Variables | `bereq`, `server`, `now` | | | | +-------------+----------------------------------------------+ -| Return | `fetch`,`abandon` | +| Return | `fetch`, `abandon` | | statements | | +-------------+----------------------------------------------+ | Next state | `vcl_backend_response`, `vcl_backend_error` | @@ -1417,9 +1417,9 @@ The built-in VCL is empty: +=============+==============================================+ | Context | Backend request | +-------------+----------------------------------------------+ -| Variables | `bereq`,`beresp`, `server`, `now` | +| Variables | `bereq`, `beresp`, `server`, `now` | +-------------+----------------------------------------------+ -| Return | `deliver`,`retry`,`abandon` | +| Return | `deliver`, `retry`, `abandon` | | statements | | +-------------+----------------------------------------------+ | Next state | `vcl_backend_error` | @@ -1595,7 +1595,7 @@ Varnish Modules With Varnish 4, Varnish Modules have become quite mature. Varnish Modules are basically VCL extensions, but with a little extra on the side. They can be used to solve anything from converting text form lowercase to uppercase, -to cryptographic hash functions to memcached integration. Wether it is a +to cryptographic hash functions to memcached integration. Whether it is a good idea or not, is a different question. Varnish already ships with two vmods. The standard vmod, or "std" vmod, @@ -1686,7 +1686,7 @@ sites could look like this: return (synth(503)); } } else { - # 401 Unahtorized if someone outside of the + # 401 Unauthorized if someone outside of the # "monitors" ACL asks for health state. return (synth(401)); } @@ -1702,12 +1702,12 @@ sites could look like this: unset beresp.http.set-cookie; } # Be very cautious about hit-for-pass objects. Only allow - # Varnish to disable the cache for 1 second at a time. Unless + # Varnish to disable the cache for 1 second at a time, unless # the backend itself provides a max-age. if (beresp.uncacheable && beresp.http.cache-control !~ "max-age") { set beresp.ttl = 1s; } - # If the request was a succes (200 OK) and it was for an image, + # If the request was a success (200 OK) and it was for an image, # ensure a minimum cache time. if (beresp.status == 200 && bereq.url ~ "^/images") { if (beresp.ttl < 600s) { @@ -1769,7 +1769,7 @@ There are a large number of states you can modify, but in practical usage, it's rare that you end up using more than three or four of them. In chapters to come, we will go through a number of scenarios that are both -common and uncommon. But because VCL is a language, there isn't finite set +common and uncommon. But because VCL is a language, there isn't a finite set of tasks you can use it for. It's really up to how your application works. Hopefully, this chapter can function as a reference for your future VCL diff --git a/chapter-5.rst b/chapter-5.rst index e75787b..5c71a47 100644 --- a/chapter-5.rst +++ b/chapter-5.rst @@ -3,8 +3,8 @@ Intelligent traffic routing .. warning:: - I expect this chapter to change significantly throught its creation, and - possibly throught the creation of the rest of the book. It should be + I expect this chapter to change significantly throughout its creation, and + possibly throughout the creation of the rest of the book. It should be seen in context with chapter 4, introduction to VCL. I advise against reviewing the pedagogical aspects of the chapter until @@ -65,7 +65,7 @@ the host and port-options. But backends can have a few more options. | | | relevant: Geographic distance, virtualization. | +-----------------------+------------+------------------------------------------------------+ | first_byte_timeout | From | Timeout waiting for the very first byte of a reply. | -| | parameters | This is application-dependant. Typically, an | +| | parameters | This is application-dependent. Typically, an | | | (60s) | application will send the entire response in one go | | | | after generating it, so this is basically | | | | how long you expect/allow the application to generate| @@ -94,7 +94,7 @@ systems with greatly increased timeouts. A few questions you should ask yourself: 1. How long would a user actually wait. -2. What are you _actually_ waiting for. +2. What are you *actually* waiting for. 3. In what circumstances would you want to send traffic to a backend this slow? @@ -727,7 +727,7 @@ Stacking directors Varnish treats all backends as directors, and vice versa. Wherever you can add a backend, you can add a director. -As a result, you can add a director to an other director. Most of the time, +As a result, you can add a director to another director. Most of the time, this makes little sense. The one situation where it makes a ton of sense, however, is when you