varnish-cli

Синтаксис

Varnish CLI похож на другой интерфейс командной строки — Bourne Shell. Команды обычно завершаются новой строкой и могут принимать аргументы. Команда и её аргументы разделяются перед анализом, и поэтому аргументы, содержащие пробелы, должны быть заключены в двойные кавычки.

Это означает, что синтаксический анализ команды

help banner

эквивалентен

"help" banner

, так как двойные кавычки только указывают границы токена help.

Внутри двойных кавычек вы можете экранировать символы с помощью \ (обратный слэш). \n, \r и \t переводятся в новые строки, возвраты каретки и табуляции. Двойные кавычки и сами обратные слэши могут быть экранированы как \” и \\ соответственно.

Для ввода символов в восьмеричном формате используйте синтаксис \nnn. Шестнадцатеричные символы можно вводить с помощью синтаксиса \xnn.

Команды могут не завершаться новой строкой, когда используется оболочный here document (here-document или heredoc). Формат here document:

<< word
     here document
word

слово может быть любой непрерывной строкой, выбранной для того, чтобы гарантировать, что она не появляется естественным образом в последующем here document. Традиционно используются EOF или END.

Особенности цитирования

Интеграция с Varnish CLI может быть иногда неожиданной, когда дело доходит до цитирования. Например, в Bourne Shell разделитель, используемый в here document, может или не может быть разделен пробелами от токена <<.

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 document может быть добавлен, и фактический VCL может быть загружен:

vcl.inline test << EOF
vcl 4.0;

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

Существенное различие с оболочковым here document заключается в обработке токена <<. Так же как имена команд могут быть цитированы, токен here document сохраняет своё значение, даже в цитированном виде:

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

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

При использовании фронтенда для Varnish-CLI, такого как varnishadm, необходимо учитывать двойное расширение, происходящее сначала в оболочке, запускающей команду 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

Если вы используете цитирование с here document, вы должны заключить его в многострочный аргумент оболочки:

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

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

Ещё одно отличие от оболочного here document заключается в том, что на одной командной строке может использоваться только один here document. Например, это можно сделать в скрипте оболочки:

#!/bin/sh

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

Ожидаемый вывод:

hello
world

В Varnish CLI только последний параметр может использовать форму here document, что сильно ограничивает количество команд, которые могут их эффективно использовать. Попытка использовать несколько here document учитывает только последний.

Например:

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

Это концептуально приводит к следующей командной строке:

• "command"
• "argument"
• "<<"
• "EOF1"
• "heredoc1\nEOF1\nheredoc2\n"

Другие особенности включают расширение переменных оболочки, вызывающей varnishadm, но это не напрямую связано с Varnish CLI. Если вы правильно поставите цитирование, у вас всё должно быть в порядке, даже с сложными командами.

JSON

Ряд команд с информационными ответами поддерживают параметр -j для вывода в формате JSON, как указано ниже. Верхняя структура ответа JSON — массив с этими первыми тремя элементами:

• Номер версии формата JSON (целое число)
• Массив строк, составляющих только что полученную команду CLI
• Время генерации ответа в виде временной метки Unix в секундах с миллисекундной точностью (с плавающей точкой)

Остальные элементы массива составляют данные, специфичные для команды CLI, и их структура и содержимое зависят от команды.

Например, ответ на status -j содержит только строку в верхнем массиве, указывающую состояние дочернего процесса ("running", "stopped" и т. д.):

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

Ответы JSON на другие команды могут содержать более длинные списки элементов, которые могут иметь простые типы данных или представлять структурированные объекты.

Вывод JSON возвращается только в случае успешного выполнения команды. Вывод для ответа об ошибке всегда такой же, как и для команды без параметра -j.

Команды

Шаблон бэкенда

Шаблон бэкенда может быть именем бэкенда или комбинацией имени VCL и имени бэкенда в формате «VCL.бэкенд». Если имя VCL опущено, предполагается активный VCL. Поддерживается частичное соответствие имён бэкенда и VCL с использованием символов подстановки в стиле оболочки, например, звёздочка (*).

Примеры:

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

Выражения запрета

Выражение запрета состоит из одного или нескольких условий. Условие состоит из поля, оператора и аргумента. Условия могут быть объединены по принципу «И» с помощью «&&».

Поле может быть любой переменной из 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 автоматически обрабатывать её.