varnish—vcl語法

VCL

varnish配置語言

介紹

varnish是一個專門用于描述varnish請求處理和文件緩存策略規則的語言。

當一個新的配置加載后，varnishd管理進程將會將其轉換為C代碼并編譯，然后加載到服務器進程中。

本文檔側重于VCL的語法。對于語法和語義的完整介紹，和示例可以參閱https://www.varnish-cache.org/docs/?。

從varnish 4.0版本開始，每一個VCL文件都必須在文件開始處說明版本號VCL 4.0。

運算符

在VCL中可以使用以下運算符：

• =?賦值運算符
• ==?比較運算符
• ~?匹配運算符。既可以使用正則表達式，也可以使用ACLs。
• !?否定運算符。
• &&?邏輯與
• ||?邏輯或

條件運算

VCL有if和else語句。嵌套的邏輯可以使用elseif來實現（elsif/elif/else if這幾個是一樣的）。

請注意，VCL中沒有任何的循環和迭代器。

字符串、布爾值、時間、時間單位和整數

在varnish中有各種數據類型，你可以設置或者取消這些：

set req.http.User-Agent = "unknown"; unset req.http.Range;

字符串

基本的字符串都是以雙引號包括，不得包含換行符。長字符串包括在{"..."}中。他們可能會包含單雙引號、換行符以及除了NUL(0x00)以外的其他控制字符。

布爾型

布爾型可以是true或者false。

時間

VCL中有時間類型，函數now返回一個時間。持續的時間可以被添加到一個時間中，來成為另外一個時間。在字符串中它會返回一個格式化的字符串。

持續時間

持續時間可以使用一個數字加一個單位來限定。數量可以是實數，因此1.5w也是被允許的。

• ms?毫秒
• s?秒
• m?分鐘
• h?小時
• d?天
• w?周/星期
• y?年

整數

某些字段可能是整數，在字符串語境下，它會返回一個字符串。

實數

VCL中可以使用實數，和整數一樣，在字符串的語境下，它會返回字符串。

正則表達式

varnish支持Perl兼容的正則表達式(PCRE)。有關完整的說明可以參見PCRE(3)手冊。

要發送一個標識給PCRE引擎，例如做不區分大小寫的匹配，括號內添加一個問號。例如：

# If host is NOT example dot com.. if (req.http.host !~ "(?i)example.com$") {... }

包含語句

在另外一個文件中包含一個VCL文件可以使用include關鍵字：

include "foo.vcl";

導入語句

導入語句主要用來加載varnish模塊(VMODs)。

import std; sub vcl_recv {std.log("foo"); }

注釋

單行注釋可以使用//或者#。如果是多行注釋的話可以使用/* block */。例如：

sub vcl_recv {// Single line of out-commented VCL.# Another way of commenting out a single line./*Multi-line block of commented-out VCL.*/ }

后端定義

一個后端聲明創建和初始化唯一后端對象。聲明使用關鍵詞backend后面跟一個后端名字。實際的聲明是在大括號里：

backend name {.attribute = "value"; }

唯一的一個強制必須有的屬性是host。屬性會從全局參數繼承默認值。以下屬性都是可用的：

• host（必須）

要使用的主機。ip地址或者可以解析為一個ip地址的hostname都是可以的。

• port

varnish應該連接的服務器端口

• host_header

添加的主機頭

• connect_timeout

連接超時時間

• first_byte_timeout

varnish等待從后端接受第一個字節的超時時間，參考http://jolestar.com/varnish-timeout/

• between_bytes_timeout

varnish等待后端響應的 idel timeout

• probe

連接探針到后端

• max_connections

后端服務器最大連接數。如果varnish達到最大值，剩下的就會連接失敗。

后端可以使用?directors?。請查看?vmod_directors幫助頁面查看更多信息。

探針 Probes

探針會定時查詢后端服務器的狀態，如果訪問失敗則標記它并關閉它。探針的定義是這樣的：

probe name {.attribute = "value"; }

這里沒有必需的選項。以下選項都是可以設置的：

• url

要查詢的url，默認是“/”

• request

指定使用多個字符串來做完整的HTTP請求。.request會在每個字符串后面添加\r\n。如果指定了.request，則優先級高于.url。

• expected_response

預期的http響應碼，默認是200.

• timeout

探針的超時時間，默認是2s

• interval

探針執行的頻率，默認為5s

• initial

當varnish啟動時多少在.window中多少polls是最好的。默認的閾值為-1。在這種情況下，后臺即使出問題，只要有一個探針返回正常就被認為是健康的。

• window

我們有多少最新的數據信息，以確定后端是否健康。默認為8

• threshold

多少次返回成功，我們認為是健康的。默認為3.

權限控制列表 ACL

一個權限控制列表聲明創建初始化后，一般可以用于匹配客戶端地址：

acl localnetwork {"localhost"; # myself"192.0.2.0"/24; # and everyone on the local network! "192.0.2.23"; # except for the dial-in router }

如果一個ACL條目指定的是一個主機名，但是varnish又無法解析的話，它將會匹配和他比較的任何地址。因此，如果它有一個否定標記，它將會拒絕它相對于任何地址，這可能不是預期的。如果該條目是在括號內的，那么它將會被簡單的忽略。

為了匹配ACL的ip地址，只需要使用匹配運算符：

if (client.ip ~ localnetwork) {return (pipe); }

VCL對象

一個VCL對象可以使用new關鍵字來實例化。

sub vcl_init {new b = directors.round_robin()b.add_backend(node1); }

這只有在vcl_init中是被允許的。

子程序

子程序可以被用來提升代碼的可讀性和可重用性。

sub pipe_if_local {if (client.ip ~ localnetwork) {return (pipe);} }

在VCL中子程序不帶任何的參數，也沒有返回值。內置的子程序都是以vcl_開頭。

要調用一個子程序，可以使用call關鍵字，后面跟上子程序的名字。

sub vcl_recv {call pipe_if_local; }

return語句

當使用return(action)語句的話，那么下一步vcl_*子程序將會被執行。該動作指定下一步如何執行。

多個子程序

如果多個子程序的名稱有一個是內置定義的，那么他們就可以有順序的被連接在一起。

當VCL被編譯時，varnish內置的VCL將會被隱式的連接起來。

變量

在VCL中，你有權限訪問某個變量。其中包含請求和響應的處理。哪些變量可用取決于上下文。

bereq

• bereq

類型：HTTP

可讀性： backend

整個后端HTTP請求的數據結構。

• bereq.backend

類型： BACKEND

可讀： vcl_pipe, backend

可寫： vcl_pipe, backend

這是我們獲取數據的后端或者director

• bereq.between_bytes_timeout

類型： DURATION

可讀： backend

可寫： backend

這是從后端接收每個字節之間的超時時間。在pipe模式下是不可用的。

• bereq.connect_timeout

類型： DURATION

可讀： vcl_pipe, backend

可寫： vcl_pipe, backend

連接后端等待的超時時間。

• bereq.first_byte_timeout

類型： DURATION

可讀： backend

可寫： backend

varnish等待從后端接受第一個字節的超時時間。在pipe模式下是不可用的。

• bereq.http.

類型： HEADER

可讀： vcl_pipe, backend

可寫： vcl_pipe, backend

相應的HTTP頭

• bereq.method

類型： STRING

可讀： vcl_pipe, backend

可寫： vcl_pipe, backend

請求的類型（例如：GET和HEAD）

• bereq.proto

類型： STRING

可讀： vcl_pipe, backend

可寫： vcl_pipe, backend

用于和服務器交互的HTTP版本號

• bereq.retries

類型： INT

可讀： backend

請求重試的次數

• bereq.uncacheable

類型： BOOL

可讀： backend

指示該請求是否是不可緩存的。

• bereq.url

類型： STRING

可讀： vcl_pipe, backend

可寫： vcl_pipe, backend

請求的URL

• bereq.xid

類型： STRING

可讀： backend

請求的唯一ID

beresp

• beresp

類型： HTTP

可讀： vcl_backend_response, vcl_backend_error

整個HTTP后端響應數據。

• beresp.age

類型： DURATION

可讀： vcl_backend_response, vcl_backend_error

對象的age。

• beresp.backend

類型： BACKEND

可讀： vcl_backend_response, vcl_backend_error

這是請求的后端服務器。如果bereq.backend被設置成一個director，那么它將會是director選擇的服務器。

• beresp.backend.ip

類型： IP

可讀： vcl_backend_response, vcl_backend_error

這個響應的來源服務器IP

• beresp.backend.name

類型： STRING

可讀： vcl_backend_response, vcl_backend_error

后端響應的來源后端服務器名字。

• beresp.do_esi

類型： BOOL

可讀： vcl_backend_response, vcl_backend_error

可寫： vcl_backend_response, vcl_backend_error

布爾型。默認是false。設置為true將會解析ESI指令對象。如果req.esi是真的才會解析。

• beresp.do_gunzip

類型： BOOL

可讀： vcl_backend_response, vcl_backend_error

可寫： vcl_backend_response, vcl_backend_error

布爾型。在將對象存入緩存之前對其解壓縮。默認為false。

• beresp.do_gzip

類型： BOOL

可讀： vcl_backend_response, vcl_backend_error

可寫： vcl_backend_response, vcl_backend_error

布爾值。在存儲之前壓縮。默認為false。當http_gzip_support是開啟的時候，varnish將會從后端請求道早已經壓縮好的內容。

• beresp.do_stream

類型： BOOL

可讀： vcl_backend_response, vcl_backend_error

可寫： vcl_backend_response, vcl_backend_error

直接將對象返回給客戶端，而不需要將整個對象存入varnish。如果request是pass將不會被存到內存中。

• beresp.grace

類型： DURATION

可讀： vcl_backend_response, vcl_backend_error

可寫： vcl_backend_response, vcl_backend_error

Set to a period to enable grace.

• beresp.http.

類型： HEADER

可讀： vcl_backend_response, vcl_backend_error

可寫： vcl_backend_response, vcl_backend_error

相應的HTTP頭

• beresp.keep

類型： DURATION

可讀： vcl_backend_response, vcl_backend_error

可寫： vcl_backend_response, vcl_backend_error

設置一個時間允許有條件的后端請求。

所保持的時間會是這個時間加上ttl。

對象的ttl過期，但是還剩有keep時間，那么將會發出有條件的后端請求來更新他們。

• beresp.proto

類型： STRING

可讀： vcl_backend_response, vcl_backend_error

可寫： vcl_backend_response, vcl_backend_error

后端響應的HTTP版本號

• beresp.reason

類型： STRING

可讀： vcl_backend_response, vcl_backend_error

可寫： vcl_backend_response, vcl_backend_error

后端服務器返回的http狀態信息。

• beresp.status

類型： INT

可讀： vcl_backend_response, vcl_backend_error

可寫： vcl_backend_response, vcl_backend_error

服務器返回的http狀態碼

• beresp.storage_hint

類型： STRING

可讀： vcl_backend_response, vcl_backend_error

可寫： vcl_backend_response, vcl_backend_error

提示varnish你要將對象存儲到特定的存儲后端。

• beresp.ttl

類型： DURATION

可讀： vcl_backend_response, vcl_backend_error

可寫： vcl_backend_response, vcl_backend_error

對象剩余的存活時間，單位秒

• beresp.uncacheable

類型： BOOL

可讀： vcl_backend_response, vcl_backend_error

可寫： vcl_backend_response, vcl_backend_error

從bereq.uncacheable繼承。設置此變量可以使對象不可緩存，這個可以在緩存中得到一個一次性對象。清除變量不會有效果，并且會記錄日志提醒“Ignoring attempt to reset beresp.uncacheable”。

• beresp.was_304

類型： BOOL

可讀： vcl_backend_response, vcl_backend_error

布爾值。如果這對于后端服務器請求是一個成功的304響應，將會更新現有的緩存對象。

client

• client.identity

類型： STRING

可讀： client

可寫： client

客戶端身份，用來在client director中加載均衡。

• client.ip

類型： IP

可讀： client

客戶端的IP

local

• local.ip

類型： IP

可讀： client

TCP連接的本地IP地址。

now

• now

類型： TIME

可讀： all

當前的時間，當用在字符串上下文時返回一個格式化的字符串。

obj

• obj.age

類型： DURATION

可讀： vcl_hit

對象已經生存的時間。

• obj.grace

類型： DURATION

可讀： vcl_hit

該對象剩余的寬限時間，以秒為單位。

• obj.hits

類型： INT

可讀： vcl_hit, vcl_deliver

緩存命中此對象的計數。如果為0表示未命中。

• obj.http.

類型： HEADER

可讀： vcl_hit

相應的HTTP頭。

• obj.keep

類型： DURATION

可讀： vcl_hit

該對象剩余保留時間，以秒為單位。

• obj.proto

類型： STRING

可讀： vcl_hit

當對象被檢索時使用的HTTP協議版本。

• obj.reason

類型： STRING

可讀： vcl_hit

由服務器返回的HTTP狀態信息。

• obj.status

類型： INT

可讀： vcl_hit

服務器返回的HTTP狀態。

• obj.ttl

類型： DURATION

可讀： vcl_hit

該對象的剩余生存時間，以秒為單位

• obj.uncacheable

類型： BOOL

可讀： vcl_deliver

對象是否是不可緩存的(pass 還是 hit-for-pass)

remote

• remote.ip

類型： IP

可讀： client

TCP連接另一端的IP地址。這個可以是客戶端的IP或者代理服務器IP。

req

• req

類型： HTTP

可讀： client

整個HTTP請求的數據結構。

• req.backend_hint

類型： BACKEND

可讀： client

可寫： client

如果我們嘗試后去內容，會將bereq.backend設置為它。

• req.can_gzip

類型： BOOL

可讀： client

客戶端是否支持gzip傳輸編碼。

• req.esi

類型： BOOL

可讀： client

可寫： client

布爾值。設置為false可以禁止處理ESI。默認為true。這個變量會在將來的版本中修改，所以盡量不要用它。

• req.esi_level

類型： INT

可讀： client

目前ESI請求有多少level。

• req.hash_always_miss

類型： BOOL

可讀： vcl_recv

可寫： vcl_recv

對這個請求強制不命中緩存。如果設置為true，varnish將會忽略所有當前存在的對象，并總是從后端拉取內容。

• req.hash_ignore_busy

類型： BOOL

可讀： vcl_recv

可寫： vcl_recv

忽略緩存查找中任何繁忙的對象。你可以想象一下，如果你有兩臺服務器在查找內容，那么這個地方就可能會出現死鎖。

• req.http.

類型： HEADER

可讀： client

可寫： client

相應的HTTP頭。

• req.method

類型： STRING

可讀： client

可寫： client

請求的類型（GET或者POST）

• req.proto

類型： STRING

可讀： client

可寫： client

客戶端使用的HTTP協議的版本號。

• req.restarts

類型： INT

可讀： client

這個請求重啟的次數。

• req.ttl

類型： DURATION

可讀： client

可寫： client

• req.url

類型： STRING

可讀： client

可寫： client

請求的URL

• req.xid

類型： STRING

可讀： client

請求的唯一ID。

req_top

• req_top.http.

類型： HEADER

可讀： client

在ESI請求樹中頂層請求的HTTP頭。在非ESI請求的情況下和req.http.相同。

• req_top.method

類型： STRING

可讀： client

在ESI請求樹中頂層請求的請求方式(例如：GET或者POST。。。)。在非ESI請求的情況下和req.method是一樣的。

• req_top.proto

類型： STRING

可讀： client

在ESI請求樹中頂層請求的HTTP版本。在非ESI請求下和req.proto相同。

• req_top.url

類型： STRING

可讀： client

在ESI請求樹中頂層請求的URL。如果是非ESI請求的話和req.url相同。

resp

• resp

類型： HTTP

可讀： vcl_deliver, vcl_synth

整個響應HTTP數據結構。

• resp.http.

類型: HEADER

可讀: vcl_deliver, vcl_synth

可寫: vcl_deliver, vcl_synth

相應的HTTP頭數據

• resp.is_streaming

類型： BOOL

可讀： vcl_deliver, vcl_synth

當響應從后端進行流處理的時候返回true

• resp.proto

類型： STRING

可讀： vcl_deliver, vcl_synth

可寫： vcl_deliver, vcl_synth

響應的HTTP協議版本。

• resp.reason

類型： STRING

可讀： vcl_deliver, vcl_synth

可寫： vcl_deliver, vcl_synth

將要返回的HTTP狀態信息。

• resp.status

類型： TYPE

可讀： vcl_deliver, vcl_synth

可寫： vcl_deliver, vcl_synth

將要返回的HTTP狀態碼。

指定一個HTTP規范代碼resp.status將也會設置resp.reason設置為相應的HTTP狀態信息。

server

• server.hostname

類型： STRING

可讀： all

服務器的名字。

• server.identity

類型： STRING

可讀： all

由-i參數設置服務器的身份。如果-i參數不傳遞到varnishd，server.identity將會被設置為該實例的名稱，可以由-n參數指定。

• server.ip

類型： IP

可讀： client

接收到連接的socket的IP地址。

storage

• storage..free_space

類型： BYTES

可讀： client, backend

存儲的空閑空間，僅適用于malloc。

• storage..used_space

類型： BYTES

可讀： client， backend

存儲中已經使用的空間大小，僅使用于malloc。

• storage..happy

類型： BOOL

可讀： client, backend

以name命名的存儲的健康狀態。

函數 Functions

以下內置的函數都是可用的。

• ban(expression)

讓所有匹配到ban規則的所有對象。

• hash_data(input)

為hash輸入增加一個輸入。在內置的vcl hash_data()是使用host和url。在vcl_hash中是可用的。

• rollback()

恢復req HTTP頭到他們的原始狀態。這個函數已經被廢棄，已經被std.rollback()替代。

• synthetic(STRING)

準備一個包含STRING的合成頭。可以在vcl_synth和vcl_backend_error中是可用的。

• regsub(str, regex, sub)

將str中的內容,能夠被regex匹配到的替換成sub,只替換第一個。在sub中，\0（也可以被寫為\&）會被替換為整個匹配的字符串。\n會被第二組匹配的內容替代。

• regsuball(str, regex, sub)

這個會匹配到字符串中所有的匹配內容。regsuball()可以將str中能夠被regex匹配到的字符串統統替換為sub。

EXAMPLES

示例可以查看在線的文檔

也可以看看

• varnishd
• vmod_directors
• vmod_std

歷史

vcl是被Poul-Henning Kamp和Verdens Gang AS，Redpill Linpro 和 Varnish Software合作開發的。本手冊頁是由Per Buer, Poul-Henning Kamp, Martin Blix Grydeland, Kristian Lyngst?l, Lasse Karstensen 和其他人寫的。

版權信息

這個文檔的開源協議和varnish是一樣的，請參考許可證：

• Copyright (c) 2006 Verdens Gang AS
• Copyright (c) 2006-2015 Varnish Software AS

總結

以上是生活随笔為你收集整理的varnish---vcl语法的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。