[master] d4f456f Stop referencing the module index, since no such thing exists
Tollef Fog Heen
tfheen at varnish-cache.org
Mon Dec 3 11:58:45 CET 2012
commit d4f456f0326d02a94aed5c0b8143e77f6d180dc9
Author: Tollef Fog Heen <tfheen at varnish-software.com>
Date: Mon Dec 3 11:25:08 2012 +0100
Stop referencing the module index, since no such thing exists
Fixes #1233
diff --git a/doc/sphinx/index.rst b/doc/sphinx/index.rst
index a663170..9d948b4 100644
--- a/doc/sphinx/index.rst
+++ b/doc/sphinx/index.rst
@@ -29,7 +29,6 @@ Indices and tables
==================
* :ref:`genindex`
-* :ref:`modindex`
* :ref:`search`
diff --git a/doc/sphinx/reference/varnish-cli.rst b/doc/sphinx/reference/varnish-cli.rst
index 88b05fe..8fc4205 100644
--- a/doc/sphinx/reference/varnish-cli.rst
+++ b/doc/sphinx/reference/varnish-cli.rst
@@ -83,10 +83,11 @@ backend.set_health matcher state
Sets the health state on a specific backend. This is useful if
you want to take a certain backend out of sirculations.
-ban *field operator argument* [&& field operator argument [...]]
- Immediately invalidate all documents matching the ban
- expression. See *Ban Expressions* for more documentation and
- examples.
+ban [-t ttl] [-g grace] [-k keep] *field operator argument* [&& field operator argument [...]]
+ Sets the given ttl, grace and keep for objects matching the ban
+ expression. If none of ttl, grace or keep are given, they all
+ get set to -1, definitively removing the object from cache. See
+ *Ban Expressions* for more documentation and examples.
ban.list
All requests for objects from the cache are matched against
@@ -199,7 +200,6 @@ The argument could be a quoted string, a regexp, or an integer.
Integers can have "KB", "MB", "GB" or "TB" appended for size related
fields.
-
Scripting
---------
@@ -295,18 +295,23 @@ EXAMPLES
Simple example: All requests where req.url exactly matches the string
/news are banned from the cache::
- req.url == "/news"
+ ban req.url == "/news"
+
+Example: Same as above, but explicit in what the TTL, grace and keep
+values are set to.
+
+ ban -t -1s -g -1s -k -1s req.url == "/news"
-Example: Ban all documents where the name does not end with ".ogg",
-and where the size of the object is greater than 10 megabytes::
+Example: Set grace for all objects whose URL end with `.ogg` to 60
+seconds. Does not change the TTL or the keep of the objects.
- req.url !~ "\.ogg$" && obj.size > 10MB
+ ban -g 60s req.url !~ "\.ogg$"
Example: Ban all documents where the serving host is "example.com"
or "www.example.com", and where the Set-Cookie header received from
the backend contains "USERID=1663"::
- req.http.host ~ "^(?i)(www\.)example.com$" && obj.http.set-cookie ~ "USERID=1663"
+ ban req.http.host ~ "^(?i)(www\.)example.com$" && obj.http.set-cookie ~ "USERID=1663"
SEE ALSO
========
diff --git a/doc/sphinx/reference/vcl.rst b/doc/sphinx/reference/vcl.rst
index 98c1c47..9327ff9 100644
--- a/doc/sphinx/reference/vcl.rst
+++ b/doc/sphinx/reference/vcl.rst
@@ -324,8 +324,11 @@ regsub(str, regex, sub)
regsuball(str, regex, sub)
As regsub() but this replaces all occurrences.
-ban(ban expression)
- Bans all objects in cache that match the expression.
+ban(ban expression [, ttl= $ttl][, grace= $grace][, keep= $keep])
+ Sets the given ttl, grace and keep for objects matching the ban
+ expression. If none of ttl, grace or keep are given, they all get
+ set to -1, definitively removing the object from cache. See *Ban
+ Expressions* in varnish-cli(7) for more documentation and examples.
Subroutines
~~~~~~~~~~~
@@ -956,11 +959,34 @@ for object invalidation:
}
}
+TTL, grace and keep – when are objects removed from the cache?
+--------------------------------------------------------------
+
+There are two mechanisms that remove objects from the cache: LRU,
+which happens when the cache is full, and expiry.
+
+Objects exist in one of multiple states:
+
+ * Valid: The TTL has not yet expired and the object is served as normal
+ * Graced: The TTL has expired, but its grace period has not expired.
+ It is a grace candidate and might be delivered to clients. See grace.
+ * Kept: The TTL has expired, but the keep period has not yet
+ expired. The object is a candidate to be used for conditional
+ requests to the backend.
+
+The keep and grace intervals run in parallel, so an object will be
+kept in the cache until the time period specified by the maximum of
+TTL + grace and TTL + keep has expired. Once all the timers have
+expired, the object will be removed from the cache and any requests
+for it will cause a completely new object to be fetched from the
+backend.
+
SEE ALSO
========
* varnishd(1)
* vmod_std(7)
+* varnish-cli(7)
HISTORY
=======
More information about the varnish-commit
mailing list