← Back to branch summary

~ubuntu-branches/ubuntu/lucid/varnish/lucid

« back to all changes in this revision

Viewing changes to man/vcl.7

  • Committer: Bazaar Package Importer
  • Author(s): Stig Sandbeck Mathisen
  • Date: 2010-03-24 13:26:08 UTC
  • mfrom: (0.1.7 upstream)
  • Revision ID: james.westby@ubuntu.com-20100324132608-4uzkavctn26bdwyi
Tags: 2.1.0-1
* New upstream version
* Fix small error in man/vcl.7so

Show diffs side-by-side

added added

removed removed

Lines of Context:
man/vcl.7
1
1
.lf 1 ./../../man/vcl.7so
2
2
.\"-
3
3
.\" Copyright (c) 2006 Verdens Gang AS
4
 
.\" Copyright (c) 2006-2008 Linpro AS
 
4
.\" Copyright (c) 2006-2009 Linpro AS
5
5
.\" All rights reserved.
6
6
.\"
7
7
.\" Author: Dag-Erling Smørgrav <des@des.no>
27
27
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28
28
.\" SUCH DAMAGE.
29
29
.\"
30
 
.\" $Id: vcl.7so 4409 2009-12-16 11:21:16Z tfheen $
 
30
.\" $Id: vcl.7so 4614 2010-03-16 09:29:37Z phk $
31
31
.\"
32
32
.Dd August 10, 2007
33
33
.Dt VCL 7
61
61
in strings in VCL, which use the (%xx) escape mechanism just like URLs,
62
62
so it can be freely used in regular expressions without doubling.
63
63
.Pp
 
64
Strings are concatenated by just putting them one after each other
 
65
without any operator in between.
 
66
.Pp
64
67
Assignments are introduced with the
65
68
.Cm set
66
69
keyword.
117
120
    .between_bytes_timeout = 2s;
118
121
}
119
122
.Ed
 
123
.Pp
 
124
To mark a backend as unhealthy after number of items have been added to
 
125
it's saintmode list 
 
126
.Fa .saintmode_threshold
 
127
can be set to the maximum list size. Setting a value of 0 disables
 
128
saintmode checking entirely for that backend. The value in the backend
 
129
declaration overrides the parameter.
 
130
 
120
131
.Ss Directors
121
132
Directors choose from different backends based on health status and a
122
133
per-director algorithm.
161
172
.Fa .threshold
162
173
is how many of those must have succeeded for us to consider the
163
174
backend healthy.
 
175
.Fa .initial
 
176
is how many of the probes are considered good when Varnish starts -
 
177
defaults to the same amount as the threshold.
164
178
.Bd -literal -offset 4n
165
179
backend www {
166
180
    .host = "www.example.com";
170
184
        .timeout = 0.3 s;
171
185
        .window = 8;
172
186
        .threshold = 3;
 
187
        .initial = 3;
173
188
    }
174
189
}
175
190
.Ed
253
268
As
254
269
.Fn regsuball
255
270
but this replaces all occurrences.
256
 
.It Fn purge_hash "regex"
257
 
Purge all objects in cache whose hash strings match
258
 
.Fa regex .
259
271
.It Fn purge_url "regex"
260
272
Purge all objects in cache whose URLs match
261
273
.Fa regex .
272
284
.Pp
273
285
Subroutines in VCL do not take arguments, nor do they return values.
274
286
.Pp
275
 
If multiple subroutines with the same name are defined, they are
276
 
concatenated in the order in which the appear in the source.
277
 
.Pp
278
287
To call a subroutine, use the
279
288
.Cm call
280
289
keyword followed by the subroutine's name:
449
458
.It Cm deliver
450
459
Deliver the object to the client.
451
460
.El
452
 
.\" vcl_timeout
453
 
.It Cm vcl_timeout
454
 
Called by the reaper thread shortly before a cached document reaches
455
 
its expiry time.
456
 
.Pp
457
 
The
458
 
.Cm vcl_timeout
459
 
subroutine may terminate with one of the following keywords:
460
 
.Bl -tag -width indent
461
 
.It Cm fetch
462
 
Request a fresh copy of the object from the backend.
463
 
.It Cm discard
464
 
Discard the object.
465
 
.El
466
 
.\" vcl_discard
467
 
.It Cm vcl_discard
468
 
Called by the reaper thread when a cached document is about to be
469
 
discarded, either because it has expired or because space is running
470
 
low.
471
 
.Pp
472
 
The
473
 
.Cm vcl_discard
474
 
subroutine may terminate with one of the following keywords:
475
 
.Bl -tag -width indent
476
 
.It Cm discard
477
 
Discard the object.
478
 
.It Cm keep
479
 
Keep the object in cache.
480
 
.El
481
461
.El
482
462
.Pp
483
463
If one of these subroutines is left undefined or terminates without
486
466
See the
487
467
.Sx EXAMPLES
488
468
section for a listing of the default code.
 
469
.Ss Multiple subroutines
 
470
If multiple subroutines with the same name are defined, they are
 
471
concatenated in the order in which the appear in the source.
 
472
.Pp
 
473
Example:
 
474
.Bd -literal -offset 4n
 
475
# in file "main.vcl"
 
476
include "backends.vcl";
 
477
include "purge.vcl";
 
478
 
 
479
# in file "backends.vcl"
 
480
sub vcl_recv {
 
481
  if (req.http.host ~ "example.com") {
 
482
    set req.backend = foo;
 
483
  } elsif (req.http.host ~ "example.org") {
 
484
    set req.backend = bar;
 
485
  }
 
486
}
 
487
 
 
488
# in file "purge.vcl"
 
489
sub vcl_recv {
 
490
  if (client.ip ~ admin_network) {
 
491
    if (req.http.Cache-Control ~ "no-cache") {
 
492
      purge_url(req.url);
 
493
    }
 
494
  }
 
495
}
 
496
.Ed
 
497
.Pp
 
498
The builtin default subroutines are implicitly appended in this way.
489
499
.Ss Variables
490
500
Although subroutines take no arguments, the necessary information is
491
501
made available to the handler subroutines through global variables.
508
518
.Bl -tag -width 4n
509
519
.It Va client.ip
510
520
The client's IP address.
 
521
.It Va server.hostname
 
522
The host name of the server.
 
523
.It Va server.identity
 
524
The identity of the server, as set by the
 
525
.Fl i
 
526
parameter.
 
527
If the
 
528
.Fl i
 
529
parameter is not passed to 
 
530
.Nm varnishd ,
 
531
.Va server.identity
 
532
will be set to the name of the instance, as specified by the
 
533
.Fl n
 
534
parameter.
511
535
.It Va server.ip
512
536
The IP address of the socket on which the client connection was
513
537
received.
636
660
 
637
661
.lf 1 ./default.vcl
638
662
sub vcl_recv {
 
663
    if (req.http.x-forwarded-for) {
 
664
        set req.http.X-Forwarded-For =
 
665
            req.http.X-Forwarded-For ", " client.ip;
 
666
    } else {
 
667
        set req.http.X-Forwarded-For = client.ip;
 
668
    }
639
669
    if (req.request != "GET" &&
640
670
      req.request != "HEAD" &&
641
671
      req.request != "PUT" &&
693
723
}
694
724
 
695
725
sub vcl_fetch {
696
 
    if (!obj.cacheable) {
697
 
        return (pass);
698
 
    }
699
 
    if (obj.http.Set-Cookie) {
700
 
        return (pass);
701
 
    }
702
 
    set obj.prefetch =  -30s;
 
726
    if (!beresp.cacheable) {
 
727
        return (pass);
 
728
    }
 
729
    if (beresp.http.Set-Cookie) {
 
730
        return (pass);
 
731
    }
703
732
    return (deliver);
704
733
}
705
734
 
707
736
    return (deliver);
708
737
}
709
738
 
710
 
sub vcl_discard {
711
 
    /* XXX: Do not redefine vcl_discard{}, it is not yet supported */
712
 
    return (discard);
713
 
}
714
 
 
715
 
sub vcl_prefetch {
716
 
    /* XXX: Do not redefine vcl_prefetch{}, it is not yet supported */
717
 
    return (fetch);
718
 
}
719
 
 
720
 
sub vcl_timeout {
721
 
    /* XXX: Do not redefine vcl_timeout{}, it is not yet supported */
722
 
    return (discard);
723
 
}
724
 
 
725
739
sub vcl_error {
726
740
    set obj.http.Content-Type = "text/html; charset=utf-8";
727
741
    synthetic {"
746
760
"};
747
761
    return (deliver);
748
762
}
749
 
.lf 637 ./../../man/vcl.7so
 
763
.lf 661 ./../../man/vcl.7so
750
764
.Ed
751
765
.Pp
752
766
The following example shows how to support multiple sites running on