1VMOD_HEADER(3)                                                  VMOD_HEADER(3)
2
3
4

NAME

6       vmod_header - Header VMOD for Varnish
7

SYNOPSIS

9          import header [as name] [from "path"]
10
11          VOID append(HEADER, STRING)
12
13          VOID copy(HEADER, HEADER)
14
15          STRING get(HEADER header, REGEX regex)
16
17          VOID remove(HEADER header, REGEX regex)
18
19          VOID regsub(HTTP, REGEX regex, STRING sub, BOOL all)
20
21          HEADER dyn(HTTP, STRING)
22

DESCRIPTION

24       Varnish  Module  for  manipulation  of duplicated HTTP headers, for in‐
25       stance multiple Set-Cookie headers.
26
27       Example:
28
29          vcl 4.0;
30          import header;
31
32          backend default { .host = "192.0.2.11"; .port = "8080"; }
33
34          sub vcl_backend_response {
35              if (beresp.http.Set-Cookie) {
36                  # Add another line of Set-Cookie in the response.
37                  header.append(beresp.http.Set-Cookie, "VSESS=abbabeef");
38
39                  # CMS always set this, but doesn't really need it.
40                  header.remove(beresp.http.Set-Cookie, "JSESSIONID=");
41              }
42          }
43
44   VOID append(HEADER, STRING)
45       Description
46              Append an extra occurrence to an existing header.
47
48       Example
49              :: header.append(beresp.http.Set-Cookie, "foo=bar")
50
51   VOID copy(HEADER, HEADER)
52       Description
53              Copy all source headers to a new header.
54
55       Example
56              ::                           header.copy(beresp.http.set-cookie,
57              beresp.http.x-old-cookie);
58
59   STRING get(HEADER header, REGEX regex)
60       Description
61              Fetches  the  value  of  the first header that matches the given
62              regular expression regex.
63
64       Example
65              ::              set              beresp.http.xusr              =
66              header.get(beresp.http.set-cookie,"user=");
67
68   VOID remove(HEADER header, REGEX regex)
69       Description
70              Remove all occurrences of header that matches regex.
71
72       Example
73              :: header.remove(beresp.http.set-cookie,"^(?!(funcookie=))");
74
75   VOID regsub(HTTP, REGEX regex, STRING sub, BOOL all=0)
76       Description
77              For  every  header  line in the HTTP object, which can be one of
78              req, resp, bereq or beresp, if the line matches the regular  ex‐
79              pression  regex,  then replace it with the result of a substitu‐
80              tion using the string sub. sub may include backreferences of the
81              form  \1 through \9, which refer to capturing expressions in the
82              regex, or \0 to refer to  the  entire  matched  portion  of  the
83              header line.
84
85              If all is false, replace the first matched portion of the header
86              line with sub. This is the same operation performed by  the  VCL
87              native function regsub(). all is false by default.
88
89              If  all is true, replace each non-overlapping matched portion of
90              the header line with sub. This is the same  operation  performed
91              by native regsuball().
92
93              Note  that unlike the other functions in this VMOD, regsub() ap‐
94              plies to the entire header  line,  including  the  header  name,
95              colon separator, and header value. Take care that your substitu‐
96              tions result in valid headers, since ill-formed headers can  in‐
97              terfere with the HTTP protocol.
98
99              Consider  case sensitivity in the regex match. The standard dic‐
100              tates that header names are case insensitive, but header  values
101              are  not.  The VMOD function does not take care of that for you,
102              but you can express it in the regex  using  the  (?i)  flag,  as
103              shown in the example below (use (?-i) to turn it off).
104
105              Consider  using  the  ^  starting  anchor in regex to be sure to
106              match a header name (and not the same string  somewhere  in  the
107              middle of the line).
108
109       Example
110              ::  header.regsub(req,  "^(?i)Foo(\d):  (?-i)bar=(.*)$", "Bar\1:
111              \2")
112
113   HEADER dyn(HTTP, STRING)
114       Description
115              Return a dynamic header name.
116
117              Most other functions of this vmod  require  a  HEADER  argument,
118              which usually is a VCL-defined header like req.http.foo.
119
120              This  function  allows  to construct a header name from an arbi‐
121              trary string, which may also be dynamically created, for example
122              from a variable.
123
124              Notice that there are no syntactic checks on the STRING argument
125              by purpose in order to support exotic use cases. It is  entirely
126              up  to  the  user and at their own risk to supply a string which
127              represents a valid HTTP header name (or not).
128
129       Example
130              :: # create this request header # 42: is the  answer  header.ap‐
131              pend(header.dyn(req, 35 + 7), "is the answer");
132

ACKNOWLEDGEMENTS

134       The  development of this plugin was made possible by the sponsorship of
135       Softonic, http://en.softonic.com/ .
136
137       Also thanks to Imo Klabun and Anders Nordby for bug reports.
138

BUGS

140       You can't use dynamic regular expressions, which also  holds  true  for
141       normal regular expressions in regsub().
142
143
144
145
146                                                                VMOD_HEADER(3)