[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