Varnish-CLI

Varnish命令行界面

手册部分:

7

DESCRIPTION

Varnish有一个命令行界面(CLI)，可以控制和更改Varnish的大部分操作参数和配置，而不会中断正在运行的服务。

CLI可用于执行以下任务：

构形

您可以从CLI上传、更改和删除VCL文件。

参数

您可以通过CLI检查和更改Varnish提供的各种参数。在varnishd(1)手册页中记录了各个参数。

禁令

禁令是一种过滤器，用于防止Varnish提供过时的内容。当你发布禁令时，瓦尼什将不会提供任何 banned 对象，而不是从其后端服务器重新获取它。

流程管理

您可以通过CLI停止和启动缓存(子)进程。如果子进程已崩溃，还可以检索最新的堆栈跟踪。

如果使用-T、-M或-d调用varnishd(1)，CLI将可用。在调试模式(-d)下，CLI将处于前台，使用-T可以通过varnishadm或telnet连接到CLI，使用-M varnishd将连接回侦听服务 pushing 该服务CLI。请看 华而不实 了解更多细节。

语法

Varnish CLI类似于另一个命令行界面，即Bourne Shell。命令通常以换行符结尾，并且它们可能带有参数。该命令及其参数为 tokenized 在解析之前，因此包含空格的参数必须用双引号括起来。

这意味着对命令的解析

help banner

相当于

"help" banner

因为双引号仅指示 help 代币。

Within double quotes you can escape characters with \ (backslash). The \n, \r, and \t get translated to newlines, carriage returns, an tabs. Double quotes and backslashes themselves can be escaped with \" and \\ respectively.

To enter characters in octals use the \nnn syntax. Hexadecimals can be entered with the \xnn syntax.

时，命令不能以换行符结尾 here document (此处使用-文档或此处文档)。此处文档的格式为：：

<< word
     here document
word

word 可以是任何连续的字符串，以确保它不会自然地出现在以下内容中 here document 。传统上使用EOF或END。

报价陷阱

当涉及报价时，与Varnish CLI的集成有时会令人惊讶。例如，在Bourne Shell中，与此处文档一起使用的分隔符可以用空格分隔，也可以不用 << 令牌：：

cat <<EOF
hello
world
EOF
hello
world

使用Varnish CLI， << 和 EOF 令牌必须至少由一个空格分隔：：

vcl.inline boot <<EOF
106 258
Message from VCC-compiler:
VCL version declaration missing
Update your VCL to Version 4 syntax, and add
        vcl 4.0;
on the first line of the VCL files.
('<vcl.inline>' Line 1 Pos 1)
<<EOF
##---

Running VCC-compiler failed, exited with 2
VCL compilation failed

使用缺少的空格，可以添加HERE文档并加载实际的VCL：

vcl.inline test << EOF
vcl 4.0;

backend be {
        .host = "localhost";
}
EOF
200 14
VCL compiled.

与此处的Shell文档的一个很大区别是处理 << 代币。就像命令名可以用引号引起来一样，HERE文档标记保持其含义，即使用引号：：

vcl.inline test "<<" EOF
vcl 4.0;

backend be {
        .host = "localhost";
}
EOF
200 14
VCL compiled.

在使用Varnish-CLI的前端时 varnishadm ，我们必须考虑到正在发生的双重扩张。首先在Shell中启动 varnishadm 命令，然后在Varnish CLI本身中。当命令的参数需要空格时，您需要确保Varnish CLI将看到双引号：：

varnishadm param.set cc_command '"my alternate cc command"'

Change will take effect when VCL script is reloaded

否则，如果不引用引号，可能会收到一条看似不相关的错误消息：：

varnishadm param.set cc_command "my alternate cc command"
Unknown request.
Type 'help' for more info.
Too many parameters

Command failed with error code 105

如果您引用的是此处的文档，则必须将其括在一个Shell多行参数中：：

varnishadm vcl.inline test '<< EOF
vcl 4.0;

backend be {
        .host = "localhost";
}
EOF'
VCL compiled.

Shell Here文档的另一个不同之处在于，在一个命令行上只能使用一个Here文档。例如，可以在Shell脚本中执行此操作：：

#!/bin/sh

cat << EOF1 ; cat << EOF2
hello
EOF1
world
EOF2

预期输出为：

hello
world

对于Varnish CLI，只有最后一个参数可以使用HERE文档形式，这极大地限制了可以有效使用它们的命令的数量。尝试使用多个此处的文档时，只考虑最后一个文档。

例如：：

command argument << EOF1 << EOF2
heredoc1
EOF1
heredoc2
EOF2

这在概念上会产生以下命令行：

  • "command"

  • "argument"

  • "<<"

  • "EOF1"

  • "heredoc1\nEOF1\nheredoc2\n"

其他缺陷包括调用Shell的变量扩展 varnishadm 但这与Varnish CLI没有直接关系。如果引用正确，即使使用复杂的命令也不会有问题。

JSON

许多带有信息性响应的命令支持 -j JSON输出的参数，如下所示。JSON响应的顶级结构是一个具有以下前三个元素的数组：

  • JSON格式的版本号(整数)

  • 组成刚收到的CLI命令的字符串数组

  • 生成响应的时间，以秒为单位的Unix纪元时间，精度为毫秒(浮点数)

数组的其余元素形成特定于CLI命令的数据，其结构和内容取决于命令。

例如，对 status -j 只在顶层数组中包含一个字符串，指示子进程的状态 ("running" ， "stopped" 诸如此类)：

[ 2, ["status", "-j"], 1538031732.632, "running"
]

对其他命令的JSON响应可能具有更长的元素列表，这些元素可能具有简单的数据类型或形成结构化对象。

仅当命令执行成功时才返回JSON输出。错误响应的输出始终与没有 -j 参数。

指令

身份验证<响应>

确认身份。

backend.list [-j] [-p] [<backend_pattern>]

列出后端。

-p 还会显示探测状态。

-j 指定JSON输出。

除非 -j 为JSON输出指定，则输出格式为五列动态宽度，由空格和以下字段分隔：

  • 后端名称

  • 管理员：如何确定健康状态：

    • healthy ：设置 healthy 穿过 backend.set_health 。

    • sick ：设置 sick 穿过 backend.set_health 。

    • probe ：由探头或某些其他动态机制确定的健康状态。

    • deleted ：后端已被删除，但尚未清理。

    管理优先于健康

  • 测头 X/Y ： X 离开 Y 检查已成功

    X 和 Y 是后端特定的，可以表示探测检查、其他后端或任何其他度量。

    如果没有探测器或者导向器没有提供关于探测器检查结果的细节， 0/0 就是输出。

  • 运行状况：探测运行状况

    • healthy

    • sick

    如果没有探测器， healthy 就是输出。

  • 上次更改：上次更改运行状况的时间戳。

这里报告的健康状态是通用的。后端的健康状况也可能取决于它正在使用的上下文(例如，对象的散列)，因此从VCL可见的实际健康状态(例如，使用 std.healthy() )可能有所不同。

为 -j ，对象成员应该是不言而喻的，与上述字段匹配。 probe_message 具有以下格式 [X, Y, "state"] 如上所述，用于探头。JSON探测详细信息 (-j -p 论点)是特定于导演的。

Ackend.set_Health<后端模式> [auto|healthy|sick]

设置匹配<Backend_Pattern>的后端(S)的健康状态。

  • 使用 auto 健康状态由探头或一些其他动态机制(如果有的话)确定

  • healthy 将后端设置为可用

  • sick 将后端设置为不可用

BAN<字段><操作员><参数> [&& <field> <oper> <arg> ...]

将符合所有条件的所有对象标记为作废。

看见 BAN(字符串) 有关详情

ban.list [-j]

列出活动的禁令。

除非 -j 为JSON输出指定，则输出格式为：

  • 禁令发布的时间。

  • 引用此禁令的对象。

  • C 如果禁令完成=不再对其进行进一步测试。

  • 如果 lurker 已启用调试：

    • R 用于请求*测试

    • O 用于Obj.*测试

    • 指向横幅对象的指针

  • BAN规范

BAN规范的持续时间被标准化，例如，“7d”变为“1w”。

帮助 [-j|<command>]

显示命令/协议帮助。

-j 指定JSON输出。

panic.clear [-z]

清除最后一个死机，如果有的话，-z会清除相关的varnishstat计数器(S)

panic.show [-j]

返回最后一次恐慌(如果有的话)。

-j 指定JSON输出--死机消息以非结构化JSON字符串的形式返回。

param.reset [-j] <param>

将参数重置为默认值。

JSON输出与 param.show -j <param> 并包含更新后的值，因为它将由后续执行 param.show 。

param.set [-j] <参数><值>

设置参数值。

JSON输出与 param.show -j <param> 并包含更新后的值，因为它将由后续执行 param.show 。

这对于以后验证参数值是否没有更改以及使用JSON输出中的值将参数重置为所需的值非常有用。

param.show [-l|-j] [<param>|changed]

显示参数及其值。

带的长形式 -l 显示其他信息，包括文档以及最小值、最大值和默认值(如果为参数定义的话)。JSON输出使用指定 -j ，其中包含详细表单的信息；只有 -l 或 -j 是被允许的。如果使用指定的参数 <param> ，仅显示该参数。如果 changed 则只显示其值不同于其缺省值的那些参数。

PID [-j]

显示主进程的ID，并显示工作进程(如果它正在运行)。

-j 指定JSON输出。

ping [-j] [<timestamp>]

保持连接处于活动状态。

响应的格式为JSON，如果 -j 是指定的。

退出

密切联系。

开始

启动Varnish缓存进程。

状态 [-j]

检查Varnish缓存进程的状态。

-j 指定JSON输出。

停止播放

停止Varnish缓存进程。

storage.list [-j]

列出存储设备。

-j 指定JSON输出。

vcl.deps [-j]

列出所有加载的配置及其依赖项。

除非 -j 为JSON输出指定，则输出格式最多为两列动态宽度，由空格分隔，并带有以下字段：

  • VCL：一个VCL程序

  • 依赖关系：它所依赖的另一个VCL程序

仅列出直接依赖项，并多次列出具有多个依赖项的VCL。

Vcl.disard<NAME_Patterns>...

卸载命名配置(如果可能)。

卸载与至少一个名称模式匹配的命名配置和标签。所有匹配的配置和标签都将按照与潜在依赖项相关的正确顺序丢弃。如果某个配置或标签因为其依赖项之一将保留而无法丢弃，则不会丢弃任何内容。每个单独的名称模式必须与至少一个命名配置或标签匹配。

Vcl.inline<配置名称><QUOTE_VCLSTRING> [auto|cold|warm]

以提供的名称编译并加载VCL数据。

可通过此处单据录入多行VCL 语法 。

Vcl.bel<标签><配置名称>

将标签粘贴到配置。

VCL标签就像一个Unix符号链接，一个没有实质内容的名称，它指向另一个VCL。

当一个VCL引用另一个VCL时，标签是必需的。

vcl.list [-j]

列出所有加载的配置。

除非 -j 为JSON输出指定，则输出格式为五列或七列动态宽度，由空格和以下字段分隔：

  • 状态：活动、可用或已放弃

  • 状态：标签、冷、暖或自动

  • 温度：初始、冷、暖、忙或冷

  • BUSY：引用此VCL的次数(整数)

  • 名称：指定给此VCL或标签的名称

  • [ <- | -> ] 和标签信息最后两个字段)

    • -> ：标签“指向”指定的

    • <- (<n>标签 [s] )：VCL有<n>标签(S)

Vcl.load<配置名><文件名> [auto|cold|warm]

以提供的名称编译并加载VCL文件。

vcl.show [-v] [<configname>]

显示指定配置的源代码。

Vcl.State<配置名称>自动 |cold| 温暖的

强制命名配置的状态。

vcl.symtab

转储VCL符号表。

Vcl.use<配置名称|标签>

立即切换到命名配置。

后端模式

后端模式可以是后端名称，也可以是“VCL”格式的VCL名称和后端名称的组合。如果省略VCL名称，则假定为活动的VCL。使用Shell样式的通配符，例如星号(*)，支持后端和VCL名称的部分匹配。

示例：

backend.list def*
backend.list b*.def*
backend.set_health default sick
backend.set_health def* healthy
backend.set_health * auto

禁止使用表达式

BAN表达式由一个或多个条件组成。条件由一个字段、一个运算符和一个参数组成。条件可以与“&&”进行AND运算。

字段可以是VCL中的任何变量，例如req.url、req.http.host或obj.http.set-cookie。

运算符“==”表示直接比较，“~”表示正则表达式匹配，“>”或“<”表示大小比较。在运算符前面加上“！”对该表达式求反。

参数可以是带引号的字符串、正则表达式或整数。整数可以在与大小相关的字段中附加“KB”、“MB”、“GB”或“TB”。

VCL温度

VCL程序经历了与不同命令相关的几种状态：它可以被加载、使用，然后被丢弃。您可以加载多个VCL程序并随时从一个程序切换到另一个程序。只有一个活动的VCL，但前一个活动的VCL将保持活动，直到其所有事务结束。

随着时间的推移，如果您经常刷新VCL并保留以前的版本，资源消耗将会增加，这是您无法逃脱的。然而，大多数情况下，您只想为活动的VCL付出代价，并保留较旧的VCL，以防您需要回滚到以前的版本。

VCL温度使您可以最大限度地减少非活动VCL的占用空间。一旦VCL变冷，Varnish将释放所有可以稍后重新获得的资源。您可以手动设置VCL的温度或让Varnish自动处理它。

EXAMPLES

使用Shell样式加载多行VCL here document **

vcl.inline example << EOF
vcl 4.0;

backend www {
    .host = "127.0.0.1";
    .port = "8080";
}
EOF

禁止req.url与字符串/News：：完全匹配的所有请求

ban req.url == "/news"

禁止服务主机为“Example.com”或“www.Example.com”的所有文档，以及从后端接收的Set-Cookie标头包含“Userid=1663”的所有文档：

ban req.http.host ~ "^(?i)(www\\.)?example\\.com$" && obj.http.set-cookie ~ "USERID=1663"

AUTHORS

本手册最初由Per Buer撰写，后来由Federico G.Schwint、Dridi Boukelmount、Lasse Karstensen和Pul-Henning Kamp修改。

另请参阅